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About NetIQ Corporation 


We are a global, enterprise software company, with a focus on the three persistent challenges in your 
environment: Change, complexity and risk—and how we can help you control them. 


Our Viewpoint 


Adapting to change and managing complexity and risk are nothing new 


In fact, of all the challenges you face, these are perhaps the most prominent variables that deny 
you the control you need to securely measure, monitor, and manage your physical, virtual, and 
cloud computing environments. 

Enabling critical business services, better and faster 


We believe that providing as much control as possible to IT organizations is the only way to 
enable timelier and cost effective delivery of services. Persistent pressures like change and 
complexity will only continue to increase as organizations continue to change and the 
technologies needed to manage them become inherently more complex. 


Our Philosophy 


Selling intelligent solutions, not just software 


In order to provide reliable control, we first make sure we understand the real-world scenarios in 
which IT organizations like yours operate — day in and day out. That's the only way we can 
develop practical, intelligent IT solutions that successfully yield proven, measurable results. And 
that's so much more rewarding than simply selling software. 

Driving your success is our passion 


We place your success at the heart of how we do business. From product inception to 
deployment, we understand that you need IT solutions that work well and integrate seamlessly 
with your existing investments; you need ongoing support and training post-deployment; and you 
need someone that is truly easy to work with — for a change. Ultimately, when you succeed, we 
all succeed. 


Our Solutions 


¢ Identity & Access Governance 

e Access Management 

¢ Security Management 

¢ Systems & Application Management 
Ħ Workload Management 

¢ Service Management 
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Contacting Sales Support 


For questions about products, pricing, and capabilities, contact your local partner. If you cannot 
contact your partner, contact our Sales Support team. 


Worldwide: www.netiq.com/about_netiq/officelocations.asp 
United States and Canada: 1-888-323-6768 

Email: info@netiq.com 

Website: www.netiq.com 


Contacting Technical Support 


For specific product issues, contact our Technical Support team. 


Worldwide: www.netig.com/support/contactinfo.asp 
North and South America: 1-713-418-5555 

Europe, Middle East, and Africa: +353 (0) 91-782 677 

Email: support@netiq.com 

Website: www.netiq.com/support 


Contacting Documentation Support 


Our goal is to provide documentation that meets your needs. The documentation for this product is 
available on the NetIQ webs site in HTML and PDF formats on a page that does not require you to log 
in. If you have suggestions for documentation improvements, click comment on this topic at the 
bottom of any page in the HTML version of the documentation posted at www.netig.com/ 
documentation. You can also email Documentation-Feedback@netiq.com. We value your input and 
look forward to hearing from you. 


Contacting the Online User Community 


NetIQ Communities, the NetIQ online community, is a collaborative network connecting you to your 
peers and NetIQ experts. By providing more immediate information, useful links to helpful resources, 
and access to NetIQ experts, NetIQ Communities helps ensure you are mastering the knowledge you 
need to realize the full potential of IT investments upon which you rely. For more information, visit 
http://community.netig.com. 
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About this Book and the Library 


The Administration Guide provides an introduction to NetIQ Access Manager and details about how 
to configure Access Manager features. 


Intended Audience 


This book is intended for Access Manager administrators. It is assumed that you have knowledge of 
evolving Internet protocols, such as: 

e Extensible Markup Language (XML) 

¢ Simple Object Access Protocol (SOAP) 

¢ Security Assertion Markup Language (SAML) 

¢ Public Key Infrastructure (PKI) digital signature concepts and Internet security 

¢ Secure Socket Layer/Transport Layer Security (SSL/TLS) 

+ Hypertext Transfer Protocol (HTTP and HTTPS) 

¢ Uniform Resource Identifiers (URIs) 

+ Domain Name System (DNS) 

+ Web Services Description Language (WSDL) 


Other Information in the Library 


The library provides the following information resources: 


Installation and Upgrade Guide 
Provides an introduction to NetIQ Access Manager and describes the installation and upgrade 
procedures. 

Help 
Provides context-sensitive information and step-by-step guidance for common tasks, as well as 
definitions for each field on each window. 

Developer Documentation 


Provides a collection of developer tools and examples to design a flexible and expandable 
access management system to enable your applications to interact with the Identity 
Management capabilities of Access Manager, including federation, provisioning, and the secure 
delivery of identity information to client-based applications. 


NOTE: Contact namsdk@netiq.com for any query related to Access Manager SDK. 
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1.1 


Overview 


Access Manager is a comprehensive access management solution that provides secure access to 
web applications. Access Manager also provides seamless single sign-on across technical and 
organizational boundaries. It uses industry standards including Secure Assertions Markup Language 
(SAML) and Liberty Alliance protocols. It has a single console for management and configuration. To 
provide secure access from any location or any device, it supports multi-factor authentication, role- 
based access control, and data encryption. 


This section discusses the following topics: 


¢ Section 1.1, “How Access Manager Solves Business Challenges,” on page 25 
¢ Section 1.2, “How Access Manager Works,” on page 32 
¢ Section 1.3, “Access Manager Components and Their Features,” on page 34 


¢ Section 1.4, “Language Support,” on page 38 


How Access Manager Solves Business 
Challenges 


As networks expand to connect people and businesses throughout the world, secure access to 
business resources becomes increasingly important and more complex. Today, employees work from 
corporate, home, and mobile offices using mobile devices. Besides employees, customers and 
partners also require access to resources on your network, and your employees require access to 
resources on partners’ networks or at service providers. 


Access Manager lets you provide employees, customers, and partners with secure access to your 
network resources using any type of device. Access Manager helps you if your business faces any of 
the following access-related challenges: 


¢ Protecting resources so that only authorized users can access them whether those users are 
employees, customers, or partners. 


+ Ensuring that the users who are authorized to use a resource can access that resource 
regardless of users’ location or type of device they use. 


+ Requiring users to manage multiple passwords for authentication to web applications. 
+ Ensuring that users have access only to the resources required for their jobs. 
+ Revoking network access from users faster. 


+ Protecting users’ privacy and confidential information as they access company resources or 
partners’ resources. 


¢ Proving compliance with your business policies, privacy laws such as Sarbanes-Oxley, HIPAA, 
or European Union, and other regulatory requirements. 


¢ Providing facility to access protected resources by using token-based protocols. 


¢ Providing facility to use your existing credentials to access services from different service 
providers such as Office 365 and Salesforce. 
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1.1.1 


The following sections expand on these challenges and introduce the solutions provided by Access 
Manager. 

¢ Section 1.1.1, “Protecting Resources While Providing Access,” on page 26 

¢ Section 1.1.2, “Managing Passwords with Single Sign-On,” on page 27 

¢ Section 1.1.3, “Enforcing Business Policies,” on page 28 

¢ Section 1.1.4, “Sharing Identity Information,” on page 29 

¢ Section 1.1.5, “Protecting Identity Information,” on page 31 

¢ Section 1.1.6, “Complying with Regulations,” on page 32 


Protecting Resources While Providing Access 


The primary purpose of Access Manager is to protect resources by allowing access only to users you 
have authorized. As shown in the following illustration, those users who are authorized to use the 
protected resources, are allowed access, while unauthorized users are denied access. 
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Access Manager secures your web resources from Internet hackers. Addresses of the servers that 
host the protected resources are hidden from both external and internal users. The only way to 
access the resources is by logging in to Access Manager with authorized credentials, no matter what 
device you use. 


Access Manager protects only the resources you have set up as protected resources. It is nota 
firewall and should always be used in conjunction with a firewall product. 


Access to resources is independent of a user’s location, as shown in the following illustration. Access 
Manager provides the same secure access and same experience whether the user is accessing 
resources from your local office, from home, or from any other place with any type of device. 
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1.1.2 Managing Passwords with Single Sign-On 


Authentication through Access Manager not only establishes authorization to applications (see 
Protecting Resources While Providing Access), but it can also provide authorization to those same 
applications. With Access Manager serving as the front-end authentication, you can deploy 
standards-based web single sign-on. With single sign-on, your employees, partners, and customers 
only need to remember one password or login routine to access all corporate and web-based 
applications they are authorized to use. That means fewer help desk calls and the reduced likelihood 
of users resorting to vulnerable written reminders. 
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By simplifying the use and management of passwords, Access Manager helps you enhance users' 
experience, increase security, streamline business processes, and reduce system administration and 
support costs. 


1.1.3 Enforcing Business Policies 


28 


Determining the access policies for an organization is often complicated and difficult, but the difficulty 
pales in comparison to enforcing the policies. Your IT personnel can spend hours attempting to give 
users the correct access to resources, and hours more retracing their steps to see why authorized 
users cannot access resources. You might never know about the situations where users access 
resources they should not be accessing. 


Access Manager automates the granting and revoking of access through the use of roles and 
policies. As shown in the following illustration, users are assigned to roles that have access policies 
associated with them. Each time a user authenticates through Access Manager, the user’s access is 
determined by the policies associated with the user’s roles. 
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In the following example, users assigned to the Accounting role receive access to the Accounting 
resources, Payroll users receive access to the Payroll resources, and Accounting managers receive 
access to both the Accounting and Manager resources. 
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Because access is based on roles, you can grant access in minutes and be certain that the access is 
consistent with your business policies. You can revoke access in minutes by removing role 
assignments from users. 
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For security-minded organizations, it comes down to this simple fact: you set the policies by which 
users gain access, and Access Manager enforces them consistently and quickly. There are no 
surprises and no delays. 


You can also securely grant access to user’s private resources such as web applications, mobile 
phones, handheld devices, and desktop using access tokens. 


Sharing Identity Information 


In today’s business environment, few organizations stand alone. More than likely, you have trusted 
business partners with whom you need to share resources in a secure manner. Or, you have 
business services, such as a 401k management system, to which you need to provide employee 
access. Or, maybe your organization is the one providing services to another business. Access 
Manager provides federated identity management to enable users to seamlessly and securely 
authenticate across autonomous identity domains. 


For example, assume that you have employees who need access to your corporate applications, 
several business partners’ applications, and their 401k service, as shown in the following figure: 
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Each identity domain (your organization, your partner’s organization, and 401k service) requires an 
account and authentication to that account to access the resources. However, because you have 
used Access Manager to establish a trust relationship with the business partner and the 401k service, 
your employees can log in through Access Manager to gain access to the authorized resources in all 
three identity domains. 


Access Manager enables your employees to access resources from business partners and service 
providers. It also lets business partners access authorized resources on your network. The following 
figure illustrates this type of access. 
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In addition to simply linking user accounts in different identity domains, Access Manager also 
supports federated provisioning, which means that new user accounts can be automatically created 
in your trusted partner's (or provider’s) system. For example, a new employee in your organization 
can initiate the creation of an account in your business partner’s system through Access Manager 
rather than relying on the business partner to provide the account. Customers or trusted business 
partners can automatically create accounts in your system. 


Access Manager leverages identity federation standards including Liberty Alliance, WS-Federation, 
WS-Trust, and SAML. It also provides a facility to identify risk associated with login attempts, mitigate 
the risk and take action based on risk severity. This foundation minimizes—or even eliminates— 
interoperability issues among external partners or internal workgroups. In fact, Access Manager 
features an identical configuration process for all federation partners whether they are different 
departments within your organization or external business partners. 
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1.1.5 Protecting Identity Information 


Whenever you exchange identity information with other businesses or service providers, you must be 
concerned with protecting the privacy of your employees, customers, and partners. It is an integral 
part of trusted business partnerships and regulatory compliance: the ability to establish policies on the 
exchange of identity information. 


Access Manager enables you to determine which business and personal information from your 
corporate directory to share with others. As shown in the following illustration, you can choose to 
share only the information required to establish the account at the service provider or trusted partner: 
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Access Manager offers this built-in privacy protection for your employees, partners, and customers 
alike, wherever they are working. With Access Manager in place, your organization can guarantee 
user confidentiality. For federated provisioning, Access Manager adheres to those same policies and 
protections. 
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Complying with Regulations 


Regulations can be a hassle, but an agile, automated IT infrastructure substantially cuts costs and 
reduces the pain of compliance. By implementing access based on user identities, you can protect 
users’ privacy and confidential information. At the same time, you can reduce the amount of 
paperwork needed to prove that proper access control measures are in place. Compliance assurance 
and documentation is an inherent benefit of Access Manager. 


Specifically, Access Manager helps you stay in compliance with Sarbanes-Oxley, HIPAA, European 
Union privacy laws, and other regulatory requirements. For an internal assessment or an external 
auditor, Access Manager can generate the reports you need, turning compliance requirements into 
opportunities to develop and implement processes that improve your business practices. 


How Access Manager Works 


Access Manager deployments typically use Identity Servers and Access Gateways to provide policy- 
driven access control for HTTP services. 


Figure 1-1 illustrates the primary purposes of Access Manager: authentication, identity federation, 
authorization, and identity injection. 
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Authentication 


The Identity Server facilitates authentication for all Access Manager components. This authentication 
is shared with internal or external service providers on behalf of the user by means of assertions. 
Access Manager supports a number of authentication methods, such as name/password, RADIUS 
token-based authentication, X.509 digital certificates, Kerberos, Risk-based authentication, Time- 
Based One-Time Password (TOTP), Social authentication and OpenID Connect. You specify 
authentication methods in the contracts that you want to make available to the other components of 
Access Manager, such as Access Gateway. 


User data is stored in user stores. User stores are LDAP directory servers to which end users 
authenticate. You can configure a user store with more than one replica to provide load balancing and 
failover capability. 


Authorization 


Authentication is the process of determining who a user is. Authorization is the process of 
determining what a user is allowed to do. Access Manager allows you to configure roles and 
authorization policies, based on criteria other than authentication, to protect a resource. Authorization 
policies are dynamically applied after authentication and are enforced when a user attempts to 
access a protected resource. 


Identity Injection 


An Access Gateway lets you retrieve information from your LDAP directory, use it to inject information 
into HTML headers, query strings, or basic authentication headers, and send this information to the 
back-end web servers. Access Manager calls this technology identity injection. The web server uses 
this information to personalize content, or can use it for additional authorization decisions. Where web 
servers require additional authentication, Identity Injection can also provide the necessary credentials 
to perform a single sign-on. 


Identity Federation 


Identity federation is the association of accounts between an identity provider and a service provider. 
As shown in Figure 1-2, an employee named Steve is known as steve s. at his corporate identity 
provider. He has an account at a work-related service provider called 401k, which has set up a trust 
relationship with his company. At 401k he is known as ssmith_01. 
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Figure 1-2 Identity Federation 
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As a service provider, 401k can be configured to trust the authentication from the corporate identity 
provider. Steve can enable single sign-on and single logout by federating or linking his two accounts. 


From an administrative perspective, this type of sharing reduces identity management costs, because 
multiple organizations do not need to independently collect and maintain identity-related data, such 
as passwords. From the end user's perspective, this results in an enhanced experience by requiring 
fewer sign-ons. 


Access Manager Components and Their Features 


¢ Section 1.3.1, “Administration Console,” on page 34 
¢ Section 1.3.2, “Identity Servers,” on page 35 

¢ Section 1.3.3, “Access Gateways,” on page 36 

¢ Section 1.3.4, “Analytics Server,” on page 37 

¢ Section 1.3.5, “MobileAccess,” on page 37 

¢ Section 1.3.6, “User Portal,” on page 38 


Administration Console 


Administration Console is the central configuration and management tool for the product. It contains a 
Dashboard option, which allows you to assess the health of all Access Manager components. 


Administration Console allows you to configure and manage each component. It also allows you to 
manage resources, such as policies, hardware, and certificates, which are used by multiple 
components. 
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Identity Servers 


Identity Server is the central authentication and identity access point for all other services. It is 
responsible for authenticating users and distributing role information to facilitate authorization 
decisions. It also provides the Liberty Alliance Web Service Framework to distribute identity 
information. 


An Identity Server always operates as an identity provider and can optionally be configured to run as 
an identity consumer (also known as a service provider), by using Liberty, SAML 1.1, SAML 2.0 or 
OAuth protocols. As an identity provider, Identity Server validates authentications against the 
supported identity user store. It is the heart of the user’s identity federations or account linkage 
information. 


In an Access Manager configuration, Identity Server is responsible for managing the following tasks: 


+ 


Authentication: Verifies user identities through various forms of authentication, both local (user 
supplied) and indirect (supplied by external providers). The identity information can be some 
characteristic attribute of the user, such as a role, e-mail address, name, or job description. 
Advanced authentication mechanisms include Time-Based One-Time Password(TOTP), social 
authentication using external OAuth providers, and risk-based authentication. 


Identity Stores: Links to user identities stored in eDirectory, Microsoft Active Directory, or Sun 
ONE Directory Server. 


Identity Federation: Enables user identity federation and provides access to Liberty-enabled 
services. 


Account Provisioning: Enables service provider account provisioning, which automatically 
creates user accounts during a federation request. 


Custom Attribute Mapping: Allows you to define custom attributes by mapping Liberty Alliance 
keywords to LDAP-accessible data, in addition to the available Liberty Alliance Employee and 
Person profiles. 


SAML Assertions: Processes and generates SAML assertions. Using SAML assertions in each 
Access Manager component protects confidential information by removing the need to pass user 
credentials between the components to handle session management. 


Single Sign-On and Logout: Enables users to log in only once to gain access to multiple 
applications and platforms. Single sign-on and single logout are primary features of Access 
Manager and are achieved after the federation and trust model is configured among trusted 
providers and the components of Access Manager. 


Identity Integration: Provides authentication and identity services to Access Gateways that are 
configured to protect web servers. Access Gateway and other Access Manager components 
include an embedded service provider that is trusted by Access Manager Identity Servers. 


Roles: Provides RBAC (role-based access control) management. RBAC is used to provide a 
convenient way to assign a user to a particular job function or set of permissions within an 
enterprise to control access. Identity Server establishes the active set of roles for a user session 
each time the user is authenticated. Roles can be assigned to particular subsets of users based 
on constraints outlined in a role policy. The established roles can then be used in authorization 
policies to form the basis for granting and restricting access to particular web resources. 
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Access Gateways 


An Access Gateway provides secure access to existing HTTP-based web servers. It provides 
security services (authorization, single sign-on, and data encryption) integrated with the identity and 
policy services of Access Manager. 


Access Gateway is designed to work with Identity Server to enable single sign-on to protected web 
services. The following features facilitate single sign-on to web servers that are configured to enforce 
authentication or authorization policies: 


¢ Identity Injection: Injects the information into HTTP headers that the web server requires. 
¢ Form Fill: Automatically fills in the requested form information. 
If your web servers have not been configured to enforce authentication and authorization, you can 


configure Access Gateway to provide these services. Authentication contracts and authorization 
policies can be assigned so that they protect the entire web server or a single page. 


Access Gateway can also be configured to cache requested pages. When a user meets the 
authentication and authorization requirements, the user is sent the page from cache rather than 
requesting it from the web server, which enhances the content delivery performance. 


There are two types of Access Gateways. Both are based on the same core technology and differ 
only in their deployment method. 


Access Gateway Appliance: It is installed as a soft appliance, which includes the operating system. 
Access Gateway Service: It requires you to provide the operating system. 


Features of Access Gateway Appliance and Access Gateway Service are same but differ from the 
Linux Access Gateway. 


For more information about the differences, see Feature Comparison of Different Types of Access 
Gateways in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


For information about how to upgrade your chosen Access Gateway technology, see Upgrading 
Access Manager in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


Embedded Service Provider 


Access Gateway uses an Embedded Service Provider (ESP) to redirect authentication requests to 
Identity Server. Identity Server allows only trusted devices to participate. To trust each other, devices 
must exchange metadata. The Embedded Service Provider performs this task automatically for 
Access Gateway. The logout requests to Identity Server must be digitally signed. 
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Figure 1-3 Access Gateway Component 
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Analytics Server 


Analytics Server is a component of Access Manager that analyses the usage, performance, and 
events of Access Manager. The events are captured and filtered through Analytics Server. 


Analytics Server filters and analyzes the events that are generated from the Access Manager 
components (Access Gateway and Identity Provider). You can view the analyzed information in the 
following ways: 


¢ Dynamic graphs in Analytics Dashboard 


¢ Reports that can be generated in different formats 
¢ Raw auditing records 


Analytics Server helps the administrators to accomplish these purposes with a single soft appliance. 


The events that are generated from the Access Manager components (Identity Provider and Access 
Gateway) are collected, filtered, and saved in Analytics Server, then required events are displayed in 
Analytics Dashboard. For more information about Analytics Dashboard, see Chapter 18, “Analytics 
Dashboard,” on page 1001. 


MobileAccess 


Access Manager allows to manage users’ access to resource through mobile devices easily. You 
create appmarks for each of the Access Manager resource that you want your users to access. The 
appmark acts as a bookmark for the resource. You can control access to your resources no matter 
the type of device or location of the device. 


Access Manager allows you to manage the users’ devices and allows users also to manage their own 
devices. When users lose devices, you can easily remove access to protected resources from those 
devices through Administration Console. Users can manage their own devices from a dedicated 
portal page. 
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The new user portal page displays any appmarks you have created and assigned to the user through 
the existing Access Manager roles. The user portal page also presents the different authentication 
methods assigned to the different resources. Plus you can change easily the branding of the user 
portal page without editing any JSP files. 


User Portal 


If you want complex customization of the user portal page, Access Manager provides a customizable 
user portal page that is an application where end users can access and manage their authentications, 
federations, and profile data. The authentication methods you create in Administration Console are 
reflected in the Portal. 


Help information for the end users is provided in the user interface. If you know how to customize JSP 
pages, you can customize the portal for rebranding purposes and for creating custom login pages. 


Language Support 


The Access Manager software for installation and administration uses English and is not localized. 
Administration Console is also not localized and uses only English. 


The User Portal, which appears when the user logs directly into Identity Server, is localized and so is 
its help file. The User Portal is localized for German, French, Spanish, Italian, Japanese, Portuguese, 
Dutch, Chinese (Simplified), Chinese (Traditional), and Swedish. The language must be set in the 
client’s browser to display a language other than English. 


Access Gateway and Identity Server, which can send messages to users when an error occurs, allow 
you to customize the error pages, but you are responsible for supplying the content of the customized 
pages. For information about customizing these pages, see the following: 

¢ For Access Gateway, see Chapter 4.2.9, “Customizing Access Gateway,” on page 325. 

¢ For Identity Server, see Chapter 4.1.3, “Customizing Identity Server,” on page 254. 
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Configuring Access Manager 


This section describes how to setup a basic Access Manager configuration, perform common 
administration tasks, and manage components’ configuration. For configuring Access Manager, you 
can use the latest version of Internet Explorer, Chrome, or Firefox browsers. 


Topics include: 


¢ Chapter 2, “Configuring Administration Console,” on page 41 

¢ Chapter 3, “Setting Up a Basic Access Manager Configuration,” on page 57 

¢ Chapter 4, “Setting Up an Advanced Access Manager Configuration,” on page 251 
¢ Chapter 5, “Configuring Authentication,” on page 359 

¢ Chapter 6, “Device Fingerprinting,” on page 687 

¢ Chapter 7, “Enabling Mobile and Web Access,” on page 697 

+ Chapter 8, “Access Manager Policies,” on page 709 

¢ Chapter 9, “High Availability and Fault Tolerance,” on page 883 
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Configuring Administration Console 


¢ Section 2.1, “Configuring the Default View,” on page 41 

¢ Section 2.2, “Managing Administration Console Session Timeout,” on page 43 

¢ Section 2.3, “Managing Administrators,” on page 43 

¢ Section 2.4, “Changing the IP Address of Access Manager Devices,” on page 51 

¢ Section 2.5, “Mapping the Private IP Address to Public IP Address,” on page 55 

¢ Section 2.6, “Changing the DNS Name of Access Manager Appliance,” on page 56 


Configuring the Default View 


Access Manager has two views in Administration Console. Access Manager and its Support Packs 
used the Roles and Tasks view, with Access Manager the first listed task in the left hand navigation 
frame. It looks similar to the following: 
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administration console that provides customized secure 


ae = ae This mode displays all of the roles and tasks installed. Although 
access to network administration utilities and content 


all roles and tasks are visible, the authenticated user will still 


from any location in the world. With a global view of need the necessary rights to use the tasks. 
your network from a browser-based tool, you can 
proactively assess and respond to changing network Assigned Access 


demands. Using a roles and tasks framework, 
decentralized administration has never been easier. 


This mode displays only the roles and tasks assigned to the 
authenticated user, This mode takes full advantage of the Role 
Based Services (RBS) technology. 

The roles and tasks available depend upon the access 

mode and the rights granted to you. Collection Owner Access 


This mode displays the roles and tasks in any and all collections 
for which the authenticated user is an owner. It allows user 
Admin to use all of the roles and tasks in the collections, even if 
specific rights have not been assigned. Role Based Services (RBS) 
must be installed in order to use this mode. 


This view allows you to quickly access other tasks that you occasionally need to manage the 
configuration of the datastore are visible. 
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Access Manager looks similar to the following: 
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This view has the following advantages: 


+ You can expand and collapse the containers to see as much or as little as you want. For 
example, you can see the containers for the policies or you can see the containers and all of the 
policies in the container. 


+e You see the Access Manager components in one view. If you expand the view, any item 
displayed you can click on it and Administration Console takes you to the configuration page for 
that component. 


+ Your common tasks are easily accessed through the dashboard. For example, you quickly 
access: 


+ Auditing 
+ Certificates 
+ Troubleshooting 


+ You can see the health of the different Access Manager components from the dashboard. If the 
component is healthy, the icons are green. If the components are not healthy, the icons are 
yellow and red. 


+ You can navigate faster than in the Roles and Tasks view. 


When you install or upgrade Access Manager and log in to Administration Console, the default view is 
set to the Access Manager view. 
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2.1.1 Changing the View 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Configure Console. Locate the Header frame. 


D NetIQ Access Manager OCCIE NOQG G 


2 Click either the Roles and Tasks view © or the Access Manager view © 


2.1.2 Setting a Permanent Default View 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Change Preferences. 


2 In the left navigation frame, click Set Initial View. 
3 Select your preferred view, then click OK. 


2.2 Managing Administration Console Session 
Timeout 


The web. xml file for Tomcat specifies how long an Administration Console session can remain 
inactive before the session times out and the administrator must authenticate again. The default 
value is 30 minutes. 


To change this value: 


1 Change to the Tomcat configuration directory: 
Linux: /opt/novell/nam/adminconsole/conf/web. xml 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat\conf 
2 Open the web.xml file in a text editor and search for the <session-timeout> parameter. 
3 Modify the value and save the file. 
4 Restart Tomcat: 
Linux: /etc/init.d/novell-ac restart OR rcnovell-ac restart 
Windows: net stop Tomcat7 


net start Tomcat? 


2.3 Managing Administrators 


You can create administrators with different access controls manage them in Administration Console. 


Administration Console notifies you when another administrator makes changes to a policy container 
or to an Access Manager device such as an Access Gateway. The person who is currently editing the 
configuration is listed at the top of the page with an option to unlock and with the person’s 
distinguished name and IP address. If you select to unlock, you destroy all changes the other 
administrator has done. 
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WARNING: Locking has not been implemented on the pages for modifying Identity Server. If you 
have multiple administrators, they need to coordinate with each other so that only one administrator is 
modifying an Identity Server cluster at any given time. 


Multiple Sessions: Do not start multiple sessions of Administration Console in the same browser on 
a workstation. Browser sessions share settings that can result in problems when you apply changes 
to configuration settings. However, if you are using two different brands of browsers simultaneously, 
such as Internet Explorer and Firefox, it is possible to avoid the session conflicts. 


Multiple Administration Consoles: As long as the primary console is running, all configuration 
changes must be made at the primary console. If you make changes at both a primary console and a 
secondary console, browser caching can cause you to create an invalid configuration. 


The following sections explain how to create additional administrator accounts, how to delegate rights 
to administrators, and how to manage policy view administrators: 

¢ Section 2.3.1, “Creating Multiple Admin Accounts,” on page 44 

¢ Section 2.3.2, “Managing Policy View Administrators,” on page 45 

¢ Section 2.3.3, “Managing Delegated Administrators,” on page 45 


Creating Multiple Admin Accounts 


Administration Console is installed with one admin user account. If you have multiple administrators, 
you might want to create a user account for each one so that log files reflect the modifications done 
by each administrator. The easiest way to do this is to create a new user as a trustee of the tree root 
with [Entry Rights] for Supervisor and inheritable rights assignment This also ensures that you have 
more than one user who has full access to Administration Console. If you have only one administrator 
user and the user forgets the password, you cannot access Administration Console. 


To create a new user as a trustee of the tree root: 


1 In Administration Console Dashboard, click <user name> and then click Manage Roles & Tasks. 
2 Click Users > Create User. 


Specify all the required details to create a valid user. 


NOTE: Select the same Context that the existing administrator has. 


3 Click Rights > Modify Trustees, then select the tree root user. 
4 Add the newly created user as a trustee of the tree root user. 


5 Click Assigned Rights and specify [Entry Rights] for supervisor and inheritable rights 
assignment. 


6 Click Done. 
You can also create delegated administrators and configure them to have rights to specific 


components of Access Manager. For configuration information for this type of user, see Section 2.3.3, 
“Managing Delegated Administrators,” on page 45. 
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Managing Policy View Administrators 


The super administrators can create policy view administrators. Policy view administrators can log in 
to Access Manager with their credentials and they can only view the policy containers assigned to 
them. 


The policy view administrators are created same as creating users. For more information on creating 
users, see “Creating Users” on page 49. In step 5b, select "ou=policyviewusers, o=novell” option in 
the Context field from the Contents list 


After creating user, assign rights to the newly created user. For more information, see “Policy 
Container Administrators” on page 47. 


Managing Delegated Administrators 


As an Access Manager administrator, you can create delegated administrators to manage the 
following Access Manager components. 

¢ Individual Access Gateways or an Access Gateway cluster 

¢ Identity Server clusters 

¢ Policy containers 


IMPORTANT: You need to trust the users you assign as delegated administrators. They are granted 
sufficient rights that they can compromise the security of the system. For example if you create 
delegated administrators with View/Modify rights to policy containers, they have sufficient rights to 
implement a cross-site scripting attack by using the Deny Message in an Access Gateway 
Authorization policy. 


Delegated administrators are also granted rights to the LDAP server. They can access the 
configuration datastore with an LDAP browser. Any modifications made with the LDAP browser are 
not logged by Access Manager. To log LDAP events, you need to turn on eDirectory auditing. For 
configuration information, see “Activating eDirectory Auditing for LDAP Events” on page 49. 


By default, all users except the administrator are assigned no rights to the policy containers and the 
devices. The administrator has all rights and cannot be configured to have less than all rights. The 
administrator is the only user who has the rights to delegate rights to other users, and the only user 
who can modify keystores, create certificates, and import certificates. 


The configuration pages for delegated administrators control access to the Access Manager pages. 
They do not control access to the tasks available for the Manage Roles & Tasks view in iManager. If 
you want your delegated administrators to have rights to any of these tasks such as Directory 
Administration or Groups, you must use eDirectory methods to grant the user rights to these tasks or 
enable and configure Role-Based Services in iManager. 


To create a delegated administrator, you must first create user accounts, then assign them rights to 
the Access Manager components. 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Manage Roles & Tasks. 


2 (Optional) If you want to create a container for your delegated administrators, click Directory 
Administration > Create Object, then create a container for the administrators. 


3 To create the users, click Users > Create User and create user accounts for your delegated 
administrators. You can create the users based on the delegatedusers or policyviewusers 
context. For more information on Creating Users, see “Creating Users” on page 49. 
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In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Administrators in the Dashboard. 


Select the component you want to assign a user to manage. 


For more information about the types of rights you might want to assign for each component, see 
the following: 


e “Access Gateway Administrators” on page 47 
¢ “Policy Container Administrators” on page 47 
+ “Delegated Administrators of Identity Servers” on page 48 


To assign all delegated administrators the same rights to a component, configure All Users 
option by using the drop-down menu and selecting None, View Only, or View/Modify. 


By default, All Users is configured for None. All Users is a quick way to assign everyone View 
Only rights to a component when you want your delegated administrators to have the rights to 
view the configuration but not change it. 


To select one or more users to assign rights, click Add, then specify the following details: 


Name filter: Specify a string that you want the user’s cn attribute to match. The default value is 
an asterisk, which matches all cn values. 


Search from context: Specify the context you want used for the search. Click the down-arrow 
to select from a list of available contexts. 


Include subcontainers: Specifies whether subcontainers must be searched for users. 


8 Click Query. The User section is populated with the users that match the query. 


9 In the User section, select one or more users to whom you want to grant the same rights. 


10 


12 
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For the Access option, click the down-arrow and select one of the following values: 


View/Modify: Grants full configuration rights to the device. View/Modify rights do not grant the 
rights to manage keystores, to create certificates, or to import certificates from other servers or 
certificate authorities. View/Modify rights allow the delegated administrator to perform actions 
such as stop, start, and update the device. 


If the assignment is to a policy container, this option grants the rights to create policies of any 
type and to modify any existing policies in the container 


View Only: Grants the rights to view all the configuration options of the device or all rules and 
conditions of the policies in a container. 


None: Prevents the user from seeing the device or the policy container. 


In the Device or Policy Containers section, select the devices, the clusters, or policy containers 
that you want to assign for delegated administration. 
Click Apply. 


The rights are immediately assigned to the selected users. If the user already had a rights 
assignment to the device or policy container, this new assignment overwrites any previous 
assignments. 


After assigning a user rights, check the user’s effective rights. 


Auser’s effective rights and assigned rights do not always match. For example, if Kim is granted 
View Only rights but All Users have been granted View/Modify rights, Kim’s effective rights are 
View/Modify. 
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Access Gateway Administrators 


You can assign a user to be a delegated administrator of an Access Gateway cluster or a single 
Access Gateway that does not belong to a cluster. You cannot assign a user to manage a single 
member of a cluster. 


When a delegated administrator of an Access Gateway cluster is granted View/Modify rights, the 
administrator has sufficient rights to change the cluster configuration, to stop and start (or reboot and 
shut down), and to update Access Gateways in the cluster. However, to configure Access Gateway to 
use SSL, you need to be the admin user, rather than a delegated administrator. 


When the user is assigned View/Modify rights to manage a cluster or an Access Gateway, the user is 
automatically granted View Only rights to the master policy container. If you have created other policy 
containers, these containers are hidden until you grant the delegated administrator rights to them. 
View Only rights allows the delegated administrator to view the policies and assign them to protected 
resources. It does not allow them to modify the policies. If you want the delegated administrator to 
modify or create policies, you need to grant View/Modify rights to a policy container. 


View/Modify rights to an Access Gateway or a cluster allows the delegated administrator to modify 
which Identity Server cluster Access Gateway uses for authentication. It does not allow delegated 
administrators to update Identity Server configuration, which is required whenever Access Gateway is 
configured to trust an Identity Server. To update Identity Server, the delegated administrator needs 
View/Modify rights to Identity Server configuration. 


Policy Container Administrators 


The policy container administrators are of two types: 


+ Delegated Administrators 
¢ Policy View Administrators 


Delegated Administrators 


All delegated administrators with View/Modify rights to a device have read rights to the master policy 
container. To create or modify policies, a delegated administrator needs View/Modify rights to a policy 
container. When a delegated administrator has View/Modify rights to any policy container, the 
delegated administrator is also granted enough rights to allow the administrator to select shared 
secret values, attributes, LDAP groups, and LDAP OUs to policies. 


If you want your delegated administrators to have full control over a device and its policies, you might 
want to create a separate policy container for each delegated administrator or for each device that is 
managed by a group of delegated administrators. 


Policy View Administrators 


A policy view administrator has rights only to view policy containers. The super administrators can 
create a special type of delegated administrators called policy view administrators. The policy view 
administrators can log in to Access Manager with their credentials and they are allowed to view only 
the policy containers assigned to them. 


Using Policy Container option the super administrators can add and remove the delegated and policy 
view administrators. 


+ Adding Administrators 


+ Removing Administrators 
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Adding Policy Container Administrators 


The administrator can assign the rights to the delegated administrators and the users based on the 
policy containers. 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Administrators > Policy Containers > Add Administrators. 
2 (Optional) Specify the filter. 


3 Select the Access Rights from the list for the type of administrator. For Example -View/Modify, 
View Only, and None. The policy view administrators have only View Only rights. 


4 Select the search from context in the list. For example, “ou=delegated users, o=novell, 
ou=policyviewusers, o=novell”. Based on the user selected, the delegated or policy view 
administrators are created. 


5 (Optional) Select Include Subcontainers, if you want to add it. 
6 Click Query. The users and the policy containers are displayed for the selected query. 


7 Select User and Policy Container. The users and policy containers list are displayed based on 
the association with query. 


8 Click Apply > Close. 


Removing Policy Container Administrators 
To remove the administrators from the policy containers list, do the following: 
1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Administrators > Policy Containers > Remove Administrators. 
2 Select the check box of the user assigned to the administrator and click Remove. 
3 Click Close. 


Delegated Administrators of Identity Servers 


You cannot assign a delegated administrator to an individual Identity Server. You can only assign a 
delegated administrator to a cluster configuration, which gives the delegated administrator rights to all 
the cluster members. 


When a delegated administrator of an Identity Server cluster is granted the View/Modify rights, the 
administrator has sufficient rights to change the cluster configuration and to stop, start, and update 
Identity Servers in that cluster. The administrator is granted view rights to the keystores for each 
Identity Server in the cluster. To change any of the certificates, the administrator needs to be the 
admin user rather than a delegated administrator. 


The delegated administrator of an Identity Server cluster is granted View Only rights to the master 
policy container. If you want the delegated administrator with View/Modify rights to have sufficient 
rights to manage policies, grant the following rights: 


¢ To have sufficient rights to create Role policies, grant View/Modify rights to a policy container. 


¢ To have sufficient rights to enable Role policies, grant View Only rights to the policy containers 
with Role policies. 
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Activating eDirectory Auditing for LDAP Events 


If you are concerned that your delegated administrators might use an LDAP browser to access the 
configuration datastore, you can configure eDirectory to audit events that come from LDAP 
connections to the LDAP server. 

1 In Administration Console Dashboard, click Auditing. 


2 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Manage Roles & Tasks. 


3 Click Directory Administration > Modify Object. 
4 Click the Object Selector icon, expand the novell container, then select the eDirectory server. 


The eDirectory server uses the tree name, without the _TREE suffix, for its name. The tree name 
is displayed in the iManager view bar. 


5 Click OK > Novell Audit > eDirectory. 


6 From the Meta, Objects, and Attributes sections, select the events that you want to monitor for 
potential security problems. 


+ In the Meta section, you probably want to monitor changes made to groups and ACLs. 


+ Inthe Objects section, you probably want to monitor who is logging in and out and if objects 
are being created or deleted. 


¢ Inthe Attributes section, you probably want to monitor when attribute values are added or 
deleted. 


7 Click Apply. 
8 (Linux) Restart eDirectory and the audit server by running the following commands: 
/etc/init.d/ndsd restart 


/etc/init.d/novell-naudit restart OR rcnovell-naudit restart 


Ke] 


(Windows) Restart eDirectory and the audit server: 

9a Click Control Panel > Administrative Tools > Services. 

9b Right click NDS Server, then select Stop. 

9c Answer Yes to the prompt to stop the Novell Audit Log Server. 
9d Right click NDS Server, then select Start. 

9e Right click Novell Audit Log Server, then select Start. 


Creating Users 
After creating users, you can assign the role of a delegated administrator or policy view administrator. 


1 Log in to Access Manager. 


2 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Manage Roles & Tasks > Users > Create User. 


3 User Name: Specify the user name. This is a mandatory field. 

4 (Optional) First Name: Specify the first name of the user. 

5 Last Name: Specify the name of the delegated administrator user. This is a mandatory field.. 
6 (Optional) Full Name: Specify the full name of the user. 
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Context: Specify the context as delegated administrators.This is a mandatory field. 


7a Click object selector icon. The object selector browser displays the Browse and Search 
tabs. 


7b Click Browse tab. Select delegated users option from the Contents list. The 
delegatedusers.novell or policyviewusers.novell is displayed in the context field based on 
the selection. 


Password: Specify the password and retype the password to confirm it. 


NOTE: Failure to enter a password will allow the user to login without a password. 


(Optional) Simple Password: Select this check box to set the simple password. 


NOTE: Simple Password is required for native file access on Windows and Macintosh using the 
CIFS and AFP protocols. Simple Password is not required for normal eDirectory access. The 
Universal Password feature supersedes Simple Password. When the Universal Password 
feature is enabled, setting the Simple Password is not required. For more information about the 
Universal Password feature, see Netware 6.5 Documentation. 


(Optional) Copy from Template or User Object: Copies the attributes from a user template that 
you've created. 


(Optional) Create Home Directory: You can create a home directory for this new User object if 


you have sufficient eDirectory rights. To do this, specify the path where you want to create the 
user's home directory. 


11a Volume: Applies only to NCP-enabled volumes. 


11b Path: You must specify a valid, existing directory path.The last directory typed in the path is 
the one that is created; all other directories in the path must already exist. For example, if 
you specify the path corp/home/sclark, the directories corp and home must already exist. 
The directory sclark is the only directory created. 


(Optional) Enter or Select the title, location, department, telephone number, fax number, email 
address of the delegated user from the list. 


(Optional) Enter the description if there are any to the user. You are able to add, remove and edit 
the information as per the requirement. 


Click OK. 


After creating a user, assign rights to the newly created user. For more information, see “Policy 
Container Administrators” on page 47. 


Changing Administrator’s Password 


You can change password of Administration Console and user store’s administrators. 


Changing the Password of Administration Console Administrator 


1 


2 
3 


In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Manage Roles & Tasks. Click Users > Modify User. 


Click the Object Selector icon. 
Browse to the novell container and select the name of the admin user, then click OK. 


4 Click Restrictions > Set Password. 
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5 Specify a password in New password and confirm the password in Retype new password. 
6 Click OK > OK. 


Changing the Administration Password of the User Store 
Administrator 


Perform the following steps to change the admin password of a user store configured for Identity 
Server: 


1 Click Devices > Identity Servers > <Cluster>. 

2 Go to the Local tab and click the existing user store name in the user store’s list. 
3 Enter a password that matches the User Store password 

4 Click Apply. 


Changing the IP Address of Access Manager 
Devices 


The following sections explain how to change the IP address on the following devices: 


¢ Section 2.4.1, “Changing the IP Address of an Administration Console,” on page 51 

¢ Section 2.4.2, “Changing the IP Address of an Identity Server,” on page 52 

¢ Section 2.4.3, “Changing the IP Address of an Access Gateway Appliance,” on page 53 
¢ Section 2.4.4, “Changing the IP Address of an Access Gateway Service,” on page 54 

¢ Section 2.4.5, “Changing the IP Address of an Audit Server,” on page 55 


Changing the IP Address of an Administration Console 


Install Administration Console with the IP address that it will always use. All devices that import into 
Administration Console use this IP address to establish secure communication with Administration 
Console. 


The only tested method of changing the IP address so that all other devices trust Administration 
Console is to install a secondary console with the new IP address and then promote the secondary 
console to be the primary console. 


See the following sections: 


¢ Section 9.1, “Installing Secondary Versions of Administration Console,” on page 883 


e “Converting a Secondary Administration Console into a Primary Console” on page 1156 


Converting a secondary console into a primary console is not a simple task. The task is designed as 
a disaster recovery solution when the primary console is no longer available. 
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Changing the IP Address of an Identity Server 


These instructions assume that your Identity Server and Administration Console are not on the same 
machine. If they are on the same machine, see Section 2.4.1, “Changing the IP Address of an 
Administration Console,” on page 51. 


To move a machine or change the IP address for Identity Server: 


1 
2 
3 
4 
5 
6 


N 
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Click Devices > Identity Servers. 

Click the server name. 

On the General page, click Edit. 

Specify the new IP address in the Management IP Address field and, if necessary, a port. 
Click OK, then click Close. 

On Identity Server, stop the server communication service by using the following command: 
Linux: /etc/init.d/novell-jcc stop OR rcnovell-jcc stop 

Windows: net stop jccserver 

Change the IP address by using an operating system utility: 


Linux: Click YaST > Network Devices > Network Card, select a method, select the card, then 
click Edit. 


Windows: Click Control Panel > Network Connections > Local Area Connection > Properties > 
Internet Protocol (TCP/IP) > Properties. 


Change to the jcc directory: 

Linux: /opt/novell/devman/jcc 

Windows Server 2012: \Program Files (x86)\Novell\devman\jcc 
Run the configure command: 

Linux: conf/Configure.sh 

Windows: conf\configure.cmd 


The command must be run from the jcc directory because it needs access to files that are 
available from this directory. 


When you are prompted for the local listener IP address, enter the new IP. 


When you are prompted for the administration server IP, enter the IP address of Administration 
Console. 


Follow the prompts and accept the defaults for ports and admin user. 
Replace all references to the old IP address in the server.xml file with the new IP address: 
13a Change to the Tomcat configuration directory: 

Linux: /opt/novell/nam/idp/conf 

Windows Server 2012: \Program Files (x86)\Novell\Tomcat\conf 
13b In a text editor, open the server.xml] file. 
13c Search for the old IP address and replace it with the new IP address. 
13d Save your changes. 
Start the server communication service by using the following command: 
Linux: /etc/init.d/novell-jcc start OR rcnovell-jcc start 
Windows: net start jccserver 


Restart Tomcat: 


Configuring Administration Console 


2.4.3 


Linux: Enter the following command: 

/etc/init.d/novell-idp restart OR rcnovell-idp restart 
Windows: Enter the following commands: 

net stop Tomcat7 


net start Tomcat? 


Changing the IP Address of an Access Gateway Appliance 


To change the IP address of Access Gateway machine, you need to configure Access Gateway for 
this change. This is especially significant when Access Gateway Appliance has only one IP address. 


IMPORTANT: The new IP address must be configured in Administration Console before you change 
it on Access Gateway. If you change the address on Access Gateway first, Administration Console 
does not trust Access Gateway and cannot establish communication. 


1 Click Devices > Access Gateways > Edit > Adapter List. 


(Conditional) If the machine belongs to a cluster, select Access Gateway from the Cluster 
Member list. 


From the Adapter List, select the subnet mask that contains the IP address you want to change. 


4 Select the old IP address, click Change IP Address, specify the new IP address, then click OK. 
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This option changes all configuration instances of the old IP address to the new IP address. For 
example, any reverse proxies that have been assigned the old IP address as a listening address 
are modified to use the new IP address as the listening address. 


Click OK. 
To apply your changes, click the Access Gateways link, then click Update > OK. 
If you are physically moving the machine, move it before completing the rest of these steps. 


Check the IP address that Administration Console uses for managing Access Gateway. Click 
Access Gateways > [Name of Access Gateway] > Edit. 


If the old IP address is listed as the Management IP Address, select the new IP address. If your 
Access Gateway has multiple IP addresses, select the one that you want Administration Console 
to use for communication with Access Gateway. 


The port must only be modified if there is another device on Access Gateway that is using the 
default port of 1443. 


If the name of Access Gateway is the old IP address, modify the Name option. 
Click OK. 

Administration Console uses the configured IP address to find Access Gateway. 
On Access Gateway server, restart Tomcat: 

Linux: Enter the following command: 

/etc/init.d/novell-mag restart OR rcnovell-mag restart 

Windows: Enter the following commands: 

net stop Tomcat7 


net start Tomcat? 


If your Access Gateway stops reporting to Administration Console after completing these steps, 
trigger an auto-import. See “Triggering an Import Retry” in the NetIQ Access Manager 4.3 Installation 
and Upgrade Guide. 
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1 On Access Gateway Service, use a system utility to add the new IP address. 
Do not delete the old IP address at this time. 
Linux: Start YaST, click Network Devices > Network Card, then select the Traditional Method. 


Windows: Access the Control Panel, click Network Connections > Local Area Connection > 
Properties, then select Internet Protocol (TCP/IP). Click Properties > Advanced. 


2 In Administration Console, import the new IP address: 
2a Click Access Gateways > [Name of Access Gateway] > New IP. 
2b Click OK. 
Wait for the command to complete. 
3 Change the management IP address: 
3a On the Server Details page, click Edit. 
3b Ifthe old IP address is listed as the Management IP Address, select the new IP address. 


If your Access Gateway has multiple IP addresses, select the one that you want 
Administration Console to use for communication with Access Gateway. 


3c (Conditional) Modify the port if there is another device on Access Gateway that is using the 
default port of 1443. 


3d_ If the name of Access Gateway is the old IP address, modify the Name option. 
3e Click OK. 
Administration Console uses the configured IP address to find Access Gateway. 
4 To verify that the new IP address is being used, check the health of Access Gateway. 
5 Edit Access Gateway configuration so that the reverse proxies use the new IP address: 
You need to complete these steps for each reverse proxy. 
5a Click Access Gateways > Edit > [Name of Reverse Proxy]. 
5b (Conditional) If a member of a cluster, select the cluster member that has a new IP address. 
5c For the listening address, deselect the old IP address and select the new IP address. 
5d Apply the settings and update Access Gateway. 


5e Verify that everything is working correctly by accessing a resource protected by this reverse 
proxy. 


6 OnAccess Gateway Service machine, use a system utility to remove the old IP address. 
7 Remove the old IP address from Administration Console: 
7a Click Access Gateways > [Name of Access Gateway] > New IP. 
7b Click OK. 
Wait for the command to complete. 


7c To verify that the old address has been removed, click Edit and verify that the old address is 
not an option for the Management IP Address. 
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To move a machine or change the IP address for the audit server: 


1 In Administration Console Dashboard, click Auditing. 

2 Change the IP address for the server and, if necessary, the port. 

3 Click OK. 

4 Update all Access Gateways. 

5 Reboot all servers, including Access Gateways, to use the new configuration. 


2.5 Mapping the Private IP Address to Public IP 
Address 


Use Global Settings to configure mapping of Administration Console private IP address to public NAT 
IP address. 


Devices that cannot reach the private Administration Console IP address use the NAT IP address. 
You must specify the NAT IP addresses prior to importing devices. 


You can perform the following activities by using Global Settings: 


¢ Section 2.5.1, “Creating a New NAT IP Address Mapping,” on page 55 
¢ Section 2.5.2, “Removing a NAT IP Address Mapping,” on page 55 

¢ Section 2.5.3, “Viewing the NAT IP Address Mapping,” on page 56 

¢ Section 2.5.4, “Editing a NAT IP Address Mapping,” on page 56 


2.5.1 Creating a New NAT IP Address Mapping 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Global Settings > New. 


2 Select an IP address from the Administration Console Public IP Address list. 
3 Specify the Public NAT IP Address. 


NOTE: If NAT IP address is not provided or if a mapping already exists for the selected 
Administration Console IP, this message is displayed: 


IP Address is not valid 


4 To continue, click OK, then click Apply Changes. 
5 Click Cancel to exit. 


2.5.2 Removing a NAT IP Address Mapping 


1 In Administration Console Dashboard, click <user name> icon at the top right of the page and 
then click Global Settings 


2 Select the IP address you want to delete. 
3 Click Delete, then click OK. 
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2.5.3 Viewing the NAT IP Address Mapping 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Global Settings. You can see the list of already configured physical IP addresses and NAT 
IP addresses. 


2 Create New if the list does not contain any Physical IP Address and NAT IP Address entries. 
Physical IP Address: Specifies the physical private IP Address for Administration Console. 


Public NAT IP Address: Specifies the Public NAT IP Address. You can configure or map the 
NAT IP Address. 


3 Click Close. 


2.5.4 Editing a NAT IP Address Mapping 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Global Settings. 


2 Click Public NAT IP Address. 
3 Specify the new Public NAT IP Address. 
4 Click OK. 


2.6 Changing the DNS Name of Access Manager 
Appliance 


To change the DNS name for Access Manager Appliance, modify the DNS settings for Access 
Gateway. For information about changing the DNS name, see “Viewing and Modifying DNS Settings” 
on page 322. 
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Setting Up a Basic Access Manager 
Configuration 


The initial setup for Access Manager consists of installing the components and setting up Identity 
Server and Access Gateway to protect resources running on an HTTP web server. 


This chapter describes the following topics and tasks: 


+ 


+ 


+ 


+ 


+ 


Section 3.1, “Understanding Access Manager Process Flow,” on page 57 
Section 3.2, “Prerequisites for Setup,” on page 58 

Section 3.3, “Configuring an Identity Server,” on page 59 

Section 3.4, “Identity Servers Cluster,” on page 62 

Section 3.5, “Configuring Identity Server Shared Settings,” on page 80 

Section 3.6, “Configuring Access Gateway,” on page 105 

Section 3.7, “Access Gateways Clusters,” on page 111 

Section 3.8, “Protecting Web Resources Through Access Gateway,” on page 118 
Section 3.9, “Configuring Trusted Providers for Single Sign-On,” on page 174 
Section 3.10, “Configuring Single Sign-On to Specific Applications,” on page 204 
Section 3.11, “Configuring a Protected Identity Server Through Access Gateways,” on page 220 


Section 3.12, “Sample Configuration for Protecting an Application Through Access Manager,” on 
page 227 


Understanding Access Manager Process Flow 


The following figure illustrates the components and process flow that make up a basic configuration. 


Figure 3-1 Basic Process Flow 


Identity Server LDAP Directory 


a 
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1. 
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User Access Gateway Web Server Web Page 


(with basic authentication) 


The user sends a request to Access Gateway for access to a protected resource. 


Access Gateway redirects the user to Identity Server, which prompts the user for a username 
and password. 
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3. Identity Server verifies the username and password against an LDAP directory user store 
(eDirectory, Active Directory, or Sun ONE). 


4. Identity Server returns an authentication artifact to Access Gateway through the browser in a 
query string. 


5. Access Gateway retrieves the user’s credentials from Identity Server through the SOAP channel 
in the form of a SOAP message. 


6. Access Gateway injects the basic authentication information into the HTTP header. 
7. The web server validates the authentication information and returns the requested web page. 


You configure the Access Manager so that a user can access a resource on a web server whose 
name and address are hidden from the user. This basic configuration sets up communication 
between the following four servers: 


Figure 3-2 Basic Configuration 


Server 1 Server 3 
Identity Server LDAP Directory 


Server 2 es Server 4 
Access Gateway Web Server 


Public DNS Name: 
www.mytest.com 


DNS Name: 
IP Address: IP Address: 
10.10.167.53:80 10.15.70.21 


mywebserver.com 
Although other configurations are possible, this section explains the configuration tasks for this basic 
Access Manager Appliance configuration. This section explains how to set up communication using 
HTTP. For HTTPS over SSL, see Chapter 17, “Enabling SSL Communication,” on page 977. 


Prerequisites for Setup 


The following are prerequisites for setting up a basic Access Manager configuration: 


O Access Manager version of iManager (Access Manager Administration Console) is installed. 
O An Identity Server is installed. 

O An Access Gateway is installed. 
o 


An LDAP directory store with a test user added. This store can be eDirectory, Active Directory, or 
Sun ONE. 


A DNS server or modified host files to resolve DNS names and provide reverse lookups. For 
information on which host files need to be modified, see “Configuring Name Resolution” on 
page 231. 
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O Aweb server (IIS or Apache). The web server must have three directories with three HTML 
pages. The first directory (public) must contain a page (such as index.html) for public access. 
This page needs to provide two links: 


+ Alink to a page in the protected directory. You will configure Access Gateway to require 
authentication before allowing access to this page. You do not need to configure the web 
server to protect this page. 


+ Alink to a page in the basic directory. You must already have configured your web server to 
require basic authentication before allowing access to this page. See your web server 
documentation for instructions on setting up basic authentication. (This type of access is 
optional, but explained because it is fairly common.) 


If you do not have a web server that you can use for this type of access, you might prefer to 
configure Access Manager for the sample web pages we provide. See Chapter 3.12, “Sample 
Configuration for Protecting an Application Through Access Manager,” on page 227. 


O Aclient workstation with a browser with browser pop-ups enabled. 


Configuring an Identity Server 


Post installation, create an Identity Server configuration that defines how an Identity Server or Identity 
Server cluster operates. 


When creating Identity Server configuration, specify the following information: 


+ The DNS name for Identity Server. 


+ The IP address of an LDAP directory (user store). The LDAP directory is used to authenticate 
users. The trusted root certificate of the user store is imported to provide secure communication 
between Identity Server and the user store. 


+ The distinguished name and password of the administrator of the LDAP user store. 


NOTE: This task is a basic setup to help you become familiar with Access Manager. It discusses only 
the required fields for creating a configuration. For information about all fields in the interface, see 
Section 3.4, “Identity Servers Cluster,” on page 62. 


To create an Identity Server configuration: 


1 On a client workstation, enable browser pop-ups, then log in to Administration Console. 
2 Click Devices > Identity Servers. 
3 Select the check box next to Identity Server, then click New Cluster. 
Selecting the server assigns it to the cluster configuration. 
4 Inthe New Cluster dialog box, specify a name for the cluster configuration. 


If you did not select the server in the previous step, you can now select the server or servers that 
you want to assign to this configuration. 


5 Click OK. 
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6 Specify the following properties for your Identity Server configuration: 


Field Description 


Name The name by which you want to refer to Identity Server 
configuration. This field is populated with the name you provided in 
the New Cluster dialog box. You can change the name here, if 
necessary. 


Base URL The application path for Identity Server. Identity Server protocols 
rely on this base URL to generate URL endpoints for each protocol. 


+ Protocol: The communication protocol. Select HTTP for a 
basic setup. 


+ Domain: The domain name used to access Identity Server. 
For a basic setup, this is the DNS name of the machine on 
which you installed Identity Server. Using an IP address is not 
recommended. 


+ Port: The port values for the protocol. For HTTP, this is 8080. 


¢ Application: Identity Server application path. Leave the 
default value as nidp. 


Click Next. 
The system displays the Organization page. 


Use this page to specify organization information for Identity Server configuration. The 
information you specify on this page is published in the metadata of Liberty 1.2 and SAML 
protocols. The metadata is traded with federation partners and supplies various information 
regarding contact and organization information located at Identity Server. 


Specify values in the following fields: 
Name: The name of the organization. 


Display Name: The display name for the organization. This can be the same as the name of the 
organization. 


URL: The organization’s URL for contact purposes. 
Optional fields include Company, First Name, Last Name, Email, Telephone, and Contact Type. 
Click Next. 


The system displays the User Store page.Use this page to configure the user store that 
references users in your organization. User stores are LDAP directory servers to which end 
users authenticate. You can configure a user store to use more than one replica of the directory 
server, to provide load balancing and failover capability. You must reference an existing user 
store. 


For more information about the options on this page and configuring for load balancing and 
failover, see Section 5.1.1, “Configuring Identity User Stores,” on page 360. 


Name: A display name for the LDAP directory. 


Admin Name: The distinguished name of the admin user of the LDAP directory. Administrator- 
level rights are required for setting up a user store. 


Admin Password and Confirm Password: The password for the admin user and the 
confirmation for the password. 


Directory Type: The type of LDAP directory. You can specify eDirectory, Active Directory, or Sun 
ONE. 
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14 
15 
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If eDirectory has been configured to use Domain Services for Windows, eDirectory behaves like 
Active Directory. When you configure such a directory to be a user store, its Directory Type must 
be set to Active Directory for proper operation. 


Under Server Replicas, click New to specify the user store replica information. Specify an LDAP 
server that contains a read/write replica. 


Name: The display name for the LDAP directory server. 


IP Address: The IP address of the LDAP directory server. The port is set automatically to the 
standard LDAP ports. 


For information about adding multiple replicas for load balancing and failover, see Section 5.1.1, 
“Configuring Identity User Stores,” on page 360 


Select Use secure LDAP connections. The port changes to 636, which is the secure LDAP port. 


This is the only configuration we recommend for the connection between Identity Server and the 
LDAP server in a production environment. If you use port 389, usernames and passwords are 
sent in clear text on the wire. 


Click Auto import trusted root > OK. 

Select one of the certificates in the list. 

Server Certificate: To trust one certificate. 

Root CA Certificate: To trust any certificate signed by that certificate authority. 
Specify an alias, then click OK. 

An alias is a name you use to identify the certificate used by Access Manager. 
Click Close > OK. 

Under Server Replicas, verify Validation Status. 


The system displays a green check mark if the connection is valid. If it is red, you have a 
configuration error: 


+ Check the distinguished name of the admin user, password, and IP address of the replica. 
+ Ensure that the specified admin user can log in to the user store. 
+ Check for network communication problems between Identity Server and the LDAP server. 


+ Enable verbose logging on Identity Server, then search for the IP address or name of the 
user store in the log file (Linux: catalina. out; Windows: stdout . log) and identify errors. 


For logging information, see Section 21.3.1, “Configuring Logging for Identity Server,” on 
page 1038. 


Add a search context. Click New, specify the DN of the context, select a scope, then click OK. 


The search context is used to locate users in the directory. If a user exists outside of the 
specified search context and its scope (object, subtree, one level), Identity Server cannot find the 
user, and the user cannot log in. 


A username must be unique within a search context. If the search context you specify finds more 
than one user with the same username, Identity Server cannot authenticate these users. 


Click Finish. 
Restart Tomcat when prompted. 


If your Administration Console is installed on the same machine, your connection is broken. 
Refresh the page and log in to Administration Console. 


The Health status icons for the configuration and Identity Server must turn green. 


It might take several seconds for Identity Server to start and for the system to display a green 
icon. If the health icon does not turn green, see Section 24.3, “Monitoring Health of Identity 
Servers,” on page 1100. 
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3.4 


19 (Optional) Verify the configuration: 
19a In a browser, specify the base URL of Identity Server. 
19b Select a card without the locking icon. 


Cards with a locking icon require HTTPS and SSL. In this basic setup, you configured 
Identity Server to use HTTP. 


19c Log in to by using the credentials of a user in the LDAP server. 
19d (Conditional) If the URL returns an error, verify the following: 
+ The browser machine can resolve the DNS name of Identity Server. 
+ The browser machine can access the port. 
20 If you have already installed an Access Gateway, continue with one of the following: 


+ To use your own web server pages, continue with “Configuring Access Gateway” on 
page 105. 


+ To use the Digital Airlines sample web pages, continue with Chapter 3.12, “Sample 
Configuration for Protecting an Application Through Access Manager,” on page 227. 


Identity Servers Cluster 


After you install an Identity Server, you must create a cluster configuration to configure Identity 
Server. When you create a cluster, ensure that the servers are installed on the same operating 
system, either all Linux or all Windows. Even if you have only one Identity Server, you must assign it 
to a cluster configuration to configure it. If you have multiple Identity Servers, you can create multiple 
configurations and assign different Identity Servers to them as shown in Figure 3-3. 


Figure 3-3 Identity Server Configurations 


Y= Te i 

y= iS y= 

“Z= == = 

= —_ ~ 

Configuration A Configuration A Configuration B 

A iey 

Es =a 

Ly , ae , 
Identity Server 1 Identity Server 1 

ay Ey 

—_ = 

= a , 
Identity Server 2 Identity Server 2 


A cluster of Identity Servers must reside behind a Layer 4 (L4) switch. Clients access the virtual IP 
address of the cluster presented on the L4 switch, and the L4 switch alleviates server load by 
balancing traffic across the cluster. If your Identity Server is on the same machine as an 
Administration Console, and your second Identity Server is on the same machine as a secondary 
Administration Console, ensure that you are familiar with Section 9.1, “Installing Secondary Versions 
of Administration Console,” on page 883 before proceeding. 


Whenever a user accesses the virtual IP address (port 8080) assigned to the L4 switch, the system 
routes the user to one of Identity Servers in the cluster, as traffic necessitates. 
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3.4.1 


3.4.1.1 


3.4.1.2 


3.4.1.3 


The system automatically enables clustering when multiple Identity Servers exist in a group. If only 
one Identity Server exists in a group, clustering is disabled. 


IMPORTANT: You must not use a DNS round robin setup instead of an L4 switch for load balancing. 
The DNS solution works only as long as all members of the cluster are working and in a good state. If 
one of them goes down and traffic is still sent to that member, the entire cluster is compromised and 
all devices using the cluster start generating errors. 


This section describes how to set up and manage a cluster of Identity Servers: 


¢ Section 3.4.1, “Configuration Notes,” on page 63 

¢ Section 3.4.2, “Prerequisites,” on page 64 

¢ Section 3.4.3, “Setting Up a Cluster,” on page 64 

¢ Section 3.4.4, “Managing a Cluster of Identity Servers,” on page 66 


Configuration Notes 


¢ Section 3.4.1.1, “Services of the Real Server,” on page 63 
¢ Section 3.4.1.2, “A Note about Service Configuration,” on page 63 
¢ Section 3.4.1.3, “A Note about Alteon Switches,” on page 63 


Services of the Real Server 


A user’s authentication remains on the real (authentication) server cluster member that originally 
handled the user's authentication. If this server malfunctions, all users whose authentication data 
resides on this cluster member must re-authenticate unless you have enabled session failover. For 
more information about this feature, see “Configuring Session Failover” on page 72. 


Requests that require user authentication information are processed on this server. When the system 
identifies a server as not being the real server, the HTTP request is forwarded to the appropriate 
cluster member, which processes the request and returns it to the requesting server. 


A Note about Service Configuration 


If your L4 switch can perform both SSL and non-SSL health checks, you must configure the L4 switch 
only for the services that you are using in your Access Manager configuration. For example, if you 
configure the SSL service and the non-SSL service on the L4 and the base URL of your Identity 
Server configuration is using HTTP rather than HTTPS, the health check for the SSL service fails. 
The L4 switch then assumes that all Identity Servers in the cluster are down. Therefore, ensure that 
you enable only the services that are also enabled on Identity Server. 


A Note about Alteon Switches 


When you configure an Alteon switch for clustering, direct communication between real servers must 
be enabled. If direct access mode is not enabled when one of the real servers tries to proxy another 
real server, the connection fails and times out. 


To enable direct communication on the Alteon: 


1 Go to cfg > slb > adv > direct. 
2 Specify e to enable direct access mode. 
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3.4.2 


With some L4 switches, you must configure only the services that you are using. For example, if you 
configure the SSL service for the L4 switch and you have not configured SSL in Access Manager, 
then the HTTP service on the L4 switch does not work. If the health check for the SSL service fails, 
the L4 switch assumes that all the services configured to use the same virtual IP are down. 


Prerequisites 


o 


o 


o 


An L4 server is installed. You can use the same server for Identity Server clustering and Access 
Gateway clustering, provided that you use different virtual IPs. The LB algorithm can be anything 
(hash/sticky bit), defined at the Real server level. 


Persistence (sticky) sessions enabled on the L4 server. You usually define this at the virtual 
server level. 


An Identity Server configuration created for the cluster. You assign all Identity Servers to this 
configuration. See “Identity Servers Cluster” on page 62 for information about creating an 
Identity Server configuration. See “Creating a Cluster Configuration” on page 67for information 
about assigning Identity Servers to configurations. 


The base URL DNS name of this configuration must resolve via DNS to the IP address of the L4 
virtual IP address. The L4 balances the load between Identity Servers in the cluster. 


Ensure that the L4 administration server using port 8080 has the following ports open: 
¢ 8443 (secure Administration Console) 
+ 7801 (TCP) 
+ 636 (for secure LDAP) 
+ 389 (for clear LDAP, loopback address) 
¢ 524 (network control protocol on the L4 machine for server communication) 
The identity provider ports must also be open: 
+ 8080 (nonsecure login) 
+ 8443 (secure login) 
+ 1443 (server communication) 


If you are using introductions (see “Creating a Cluster Configuration” on page 67), you must 
configure the L4 switch to load balance on ports 8445 (identity provider) and 8446 (identity 
consumer). 


3.4.3 Setting Up a Cluster 


1 Install the additional Identity Servers. 


During the installation, choose option 2, Install Identity Server, from CD 1 of the Access 
Manager installation discs. Specify the IP address and administration credentials of each 
additional Identity Server. If you are installing on a machine without Administration Console, the 
installation asks you for Administration Console’s IP address. After you install Identity Servers, 
the servers are displayed on the Servers page in Identity Servers. 


2 Assign Identity Servers to the same cluster configuration. 


For more information about assigning servers to a configuration, see “Assigning an Identity 
Server to a Cluster Configuration” on page 71. 


3 Ensure that the L4 VIP is the DNS for Identity Server clusters configuration. 


4 Click Devices > Identity Servers, then click the configuration name you created for the cluster. 
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5 On the Cluster Details page, click the configuration name. 
6 Specify the following details as required: 
Name: Lets you change the name of Identity Server cluster configuration. 


Cluster Communication Backchannel: Provides a communications channel over which the 
cluster members maintain the integrity of the cluster. For example, this TCP channel is used to 
detect new cluster members as they join the cluster, and to detect members that leave the 
cluster. A small percentage of this TCP traffic is used to help cluster members determine which 
cluster member would best handle a given request. This back channel must not be confused 
with the IP address/port over which cluster members provide proxy requests to peer cluster 
members. 


+ Port: Specifies the TCP port of the cluster back channel on all of Identity Servers in the 
cluster. 7801 is the default TCP port. 


+ Encrypt: Encrypts the content of the messages that are sent between cluster members. 


Level Four Switch Port Translation: Provides an alternative to using iptables when you want 
to use port 443 on the L4 switch and port 8443 for cluster communication. This option only works 
if firewalls do not separate Identity Servers from each other and the L4 switch supports port 
translation. To use this option, configure the base URL to use port 443, then configure the 
following options: 


+ Port translation is enabled on switch: Indicates that L4 switch has been configured to 
support port translation and that incoming traffic is using a different port than the cluster 
members. 


+ Cluster member translated port: Specifies the port the cluster members are configured to 
use. The default port that must be used for HTTPS is 8443. 


If you have firewalls separating your Identity Servers or your L4 switch does not support port 
translation, you can use iptables to translate the port. For more information about iptables, see 
Translating the Identity Server Configuration Port in the NetIQ Access Manager 4.3 Installation 
and Upgrade Guide. 


IDP Failover Peer Server Count: Enables session failover. For more information about this 
feature, see “Configuring Session Failover” on page 72. 


7 Click OK. 


8 Under Cluster Members, you can refresh, start, stop, and assign servers to Identity Server 
configurations. 


9 Click OK, then update Identity Server as prompted. 
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Real Server Settings Example 


Current real servers settings: 
1: 149.44.171.116, enabled, nane 152, weight 1, tineout 10 mins, naxcon 200000 
backup none, inter Z, retry 4, restr 8 
renote disabled, proxy enabled, submac disabled 
cookie assignnent server: disabled 
exclusionary string natching: disabled 
service ports: 8443 8086 
rcal ports: 
8443: uport 8443, group 1, pbind clientip 
virtual server: 1, 149.44.174.220, enabled 
8030: uport 8080, group 1, pbind clientip 
virtua] server: 1, 149.44.174.220, enabled 
2: 149.44.174.51, enabled, nane brie, weight 1, tineout 10 mins, naxcon 200000 
backup none, inter Z, retry 4, restr 6 
renote disabled, proxy enabled, submac disabled 
cookie assignnent server: disabled 
exclusionary string natching: disabled 
service ports: 8443 8086 
real purts: 
8443: uport 8443, group 1, pbind clientip 
virtual server: 1, 149.44.174.220, enabled 
8030: uport 8080, group 1, pbind clientip 
virtual server: 1. 149.44.174.220, enabled 


Virtual Server Settings Example 


surrent virtual servers settings: 
1: 149.494.174.220, enabled, dname idp 
virtual ports: 
6443: rport 6443, group L, pbind clientip, frags 
real servers: 
1: 199.44.171.116, weight 1, enabled, backup none 
2: 199.44.174.51, weight 1, enabled, backup none 
6060: rport 8080, group 1, pbind clientip, frags 
real servers: 
1: 199.44.171.116, weight 1, enabled, backup none 
2: 149.44.174.51, weight 1, enabled, backup none 


3.4.4 Managing a Cluster of Identity Servers 


When you assign multiple Identity Servers to the same configuration, you need to install a load 
balancer that supports either Layer 4 or Layer 7. This device is referred to as an L4 switch in this 
manual. The L4 switch allows the work load to be balanced among the machines. 


Whether you have one machine or multiple machines in a cluster, the Access Manager software 
configuration process is the same. This section describes the following cluster management tasks: 
¢ Section 3.4.4.1, “Creating a Cluster Configuration,” on page 67 
¢ Section 3.4.4.2, “Assigning an Identity Server to a Cluster Configuration,” on page 71 
¢ Section 3.4.4.3, “Configuring a Cluster with Multiple Identity Servers,” on page 71 
¢ Section 3.4.4.4, “Configuring Session Failover,” on page 72 
¢ Section 3.4.4.5, “Editing Cluster Details,” on page 73 


66 Setting Up a Basic Access Manager Configuration 


3.4.4.1 


¢ Section 3.4.4.6, “Removing a Server from a Cluster Configuration,” on page 74 
¢ Section 3.4.4.7, “Enabling and Disabling Protocols,” on page 74 

¢ Section 3.4.4.8, “Modifying the Base URL,” on page 75 

¢ Section 3.4.4.9, “Configuring Identity Server Global Options,” on page 75 


Creating a Cluster Configuration 


This section discusses all the settings available when creating an Identity Server configuration. If you 
want a description of just the options required to get a functional configuration, see Section 3.3, 
“Configuring an Identity Server,” on page 59. 


An Identity Server always operates as an identity provider and can optionally be configured to run as 
an identity consumer (also known as a service provider), by using Liberty, SAML 1.1, SAML 2.0, or 
WS Federation protocols. These topics are not described in this section. 


In an Identity Server configuration, you specify the following information: 


+ The DNS name for Identity Server or clustered server site. 
¢ Certificates for Identity Server. 


¢ Organizational and contact information for the server, which is published in the metadata of the 
Liberty and SAML protocols. 


+ The LDAP directories (user stores) used to authenticate users, and the trusted root for secure 
communication between Identity Server and the user store. 
To create an Identity Server configuration: 


1 Click Devices > Identity Servers > Edit. 
2 Select Identity Server's check box, then click New Cluster. 
Selecting the server is one way to assign it to the cluster configuration. 
3 In the New Cluster dialog box, specify a name for the cluster configuration. 


If you did not select the server in the previous step, you can now select the server or servers that 
you want to assign to this configuration. 


For more information about assigning servers to a configuration, see “Assigning an Identity 
Server to a Cluster Configuration” on page 71. 


4 Click OK. 
5 Fill in the following fields to specify the Base URL for your Identity Server configuration: 


Name: Specify a name by which you want to refer to the configuration. This field is populated 
with the name you provided in the New Cluster dialog box. You can change this name here, if 
necessary. 


IMPORTANT: Carefully determine your settings for the base URL, protocol, and domain. After 
you have configured trust relationships between providers, changing these settings invalidates 
the trust model and requires a reimport of the provider's metadata. 


Modifying the base URL also invalidates the trust between the Embedded Service Provider of 
Access Manager devices. To re-establish the trust after modifying the base URL, you must 
restart the Embedded Service Provider on each device. 
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Base URL: Specify the application path for Identity Server. Identity Server protocols rely on this 
base URL to generate URL endpoints for each protocol. 


+ Protocol: Select the communication protocol. Specify HTTPS to run securely (in SSL 
mode) and for provisioning. Use HTTP only if you do not require security or have installed 
an SSL terminator in front of Identity Server. 


+ Domain: Specify the DNS name assigned to Identity Server. When you are using an L4 
switch, this DNS name must resolve to the virtual IP address set up on the L4 switch for 
Identity Servers. Using an IP address is not recommended. 


+ Port: Specify the port value for the protocol. Default ports are 8080 for HTTP or 8443 for 
HTTPS. If you want to use port 80 or 443, specify the port here. 


¢ If you are configuring a Linux Identity Server, you must also configure the operating 
system to translate the port. See Translating the Identity Server Configuration Port in 
the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


¢ If you are configuring a Windows Identity Server, you must also modify the Tomcat 
server.xml file located in the \Program Files (x86)\Novell\Tomcat\conf 
directory for Windows Server 2012. Change the ports from 8080 and 8443 to 80 and 
443, then restart the Tomcat service. 


+ Application: Specify Identity Server application. Leave the default value nidp. 
SSL Certificate: Displays the currently assigned SSL certificate. 


Identity Server comes with a test-connector certificate that you must replace to use SSL in 
your production environment. You can replace the test certificate now or after you configure 
Identity Server. If you create the certificate and replace the test-connector certificate now, you 
can save some time by restarting Tomcat only once. Tomcat must be restarted whenever you 
assign an Identity Server to a configuration and whenever you update a certificate key store. See 
“Managing the Keys, Certificates, and Trust Stores” on page 904. 


For information about how to replace the test-connector certificate, see Chapter 17, “Enabling 
SSL Communication,” on page 977. 


To configure session limits, fill in the following fields: 


LDAP Access: Specify the maximum number of LDAP connections Identity Server can create to 
access the configuration store. You can adjust this amount for system performance. 


Default Timeout: Specify the session timeout you want assigned as a default value when you 

create a contract. This value is also assigned to a session when Identity Server cannot associate 
a contract with the authenticated session. During federation, if the authentication request uses a 
type rather than a contract, Identity Server cannot always associate a contract with the request. 


Limit User Sessions: Specify whether user sessions are limited. If selected, you can specify 
the maximum number of concurrent sessions a user is allowed to authenticate. 


If you decide to limit user sessions, you must also give close consideration to the session 
timeout value (the default is 60 minutes). If the user closes the browser without logging out (or an 
error causes the browser to close), the session is not cleared until the session timeout expires. If 
the user session limit is reached and those sessions have not been cleared with a logout, the 
user cannot log in again until the session timeout expires for one of the sessions. 


When you enable this option, it affects performance in a cluster with multiple Identity Servers. 
When a user is limited to a specific number of sessions, Identity Servers must check with the 
other servers before establishing a new session. 


+ Deleting Previous User Sessions: You can configure Identity Server to delete the 
previous user sessions if the number of open sessions reaches the maximum limit of 
allowed sessions that you have specified in the Limit User Sessions field. Set the DELETE 
OLD SESSIONS OF USER option to true and restart Identity Server. For information about 
how to configure this option, see “Configuring Identity Server Global Options” on page 75. 
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Previous sessions are cleared across Identity Server clusters only when a fresh 
authentication request comes in. When Identity Server deletes previous user sessions, it 
sends a logout request to the service provider through the SOAP back channel. 


Use case: In this scenario, a user is accessing a protected resource from a machine and 
wants to access the same protected resource from another device. Identity Server will not 
give access to the user if the Limit User Sessions has reached a maximum limit. Identity 
Server must terminate the old session of the user so that the user can access the new 
session seamlessly. 


Allow multiple browser session logout: Specify whether a user with more than one session to 
the server is presented with an option to log out of all sessions. If you do not select this option, 
only the current session can be logged out. Deselect this option in instances where multiple 
users log in as guests. Then, when one user logs out, none of the other guests are logged out. 


When you enable this option, you must also restart any Embedded Service Providers that use 
this Identity Server configuration. 


To configure TCP timeouts, fill in the following fields: 
LDAP: Specify how long an LDAP request to the user store can take before timing out. 


Proxy: Specify how long a request to another cluster member can take before timing out. When 
a member of a cluster receives a request from a user who has authenticated with another cluster 
member, the member sends a request to the authenticating member for information about the 
user. 


Request: Specify how long an HTTP request to another device can take before timing out. 


To control which protocols can be used for authentication, select one or more of the following 
protocols: 


IMPORTANT: Enable only the protocols that you are using. 


If you are using other Access Manager devices such as Access Gateway, you need to enable 
the Liberty protocol. Access Manager devices use an Embedded Service Provider. If you disable 
the Liberty protocol, you disable the trusted relationships these devices have with Identity 
Server, and authentication fails. 


Liberty: Uses a structured version of SAML to exchange authentication and data between 
trusted identity providers and service providers and provides the framework for user federation. 


SAML 1.1: Uses XML for exchanging authentication and data between trusted identity providers 
and service providers. 


SAML 2.0: Uses XML for exchanging encrypted authentication and data between trusted 
identity providers and service providers and provides the framework for user federation. 


WS Federation: Allows disparate security mechanisms to exchange information about 
identities, attributes, and authentication. 


WS-Trust: Allows secure communication and integration between services by using security 
tokens. 


To continue creating Identity Server configuration, click Next. 
The system displays the Organization page. 
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Identity Servers > 


Create Cluster Configuration 


Step 2 of 3: Specify Organization 


Name: * [Digital Airlines 
Display name: * [Digital Airlines 
URL: * [www.digitalairlines.com 


Principal Contact 


Company: | 

First Name: 
Last Name: FO 
Email Address: ON 
Telephone Number: | 

Contact Type: [Other x] 


Use this page to specify organization information for Identity Server configuration. The 
information you specify on this page is published in the metadata for the Liberty 1.2 and SAML 
protocols. The metadata is traded with federation partners and supplies various information 
regarding contact and organization information located at Identity Server. 


The following fields require information: 
+ Name: The name of the organization. 
¢ Display Name: The display name for the organization. 
¢ URL: The organization’s URL for contact purposes. 
Optional fields include Company, First Name, Last Name, Email, Telephone, and Contact Type. 
10 Click Next to configure the user store. 


You must reference your own user store and auto-import the SSL certificate. See Section 5.1.1, 
“Configuring Identity User Stores,” on page 360 for information about this procedure. 


11 After you configure the user store, the system displays the new configuration on the Servers 
page. 
The status icons for the configuration and Identity Server must turn green. It might take several 
seconds for Identity Server to start and for the system to display a green icon. If it does not, it is likely 
that Identity Server is not communicating with the user store you set up. Ensure that you have 


entered the user store information correctly, and that you imported the SSL certificate to the user 
store. (Edit > Local > [User Store Name].) 
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3.4.4.2 


3.4.4.3 


Assigning an Identity Server to a Cluster Configuration 


After you create a configuration, you must assign an Identity Server to it. For clustering, you can 
assign more than one Identity Server to the configuration (see “Configuring a Cluster with Multiple 
Identity Servers” on page 71 for the steps to set up a cluster). A configuration uses any shared 
settings you have specified, such as attribute sets, user matching expressions, and custom attributes 
that are defined for the server. 

1 Click Devices > Identity Servers. 

2 On the Servers page, select the server’s check box. 

You can select all displayed servers by selecting the top-level Server check box. 
3 Click Actions > Assign to Cluster. 
4 Select the configuration’s check box, then click Assign. 


You are prompted to restart Tomcat. The status icon for Identity Server must turn green. It might 
take several seconds for Identity Server to start and for the system to display the green icon. 


Configuring a Cluster with Multiple Identity Servers 


To add capacity and to enable system failover, you can cluster a group of Identity Servers and 
configure them in a cluster configuration to act as a single server. You can also configure the cluster 
to support session failover, so that users do not need to re-authenticate when an Identity Server goes 
down. 


A cluster of Identity Servers must reside behind an L4 switch. Clients access the virtual IP (VIP) 
address of the cluster presented on the L4 switch, and the L4 switch alleviates server load by 
balancing traffic across the cluster. Whenever a user accesses the virtual IP address assigned to the 
L4 switch, the system routes the user to one of Identity Servers in the cluster, as traffic necessitates. 


To set up a cluster, complete the following tasks: 


O Install an L4 switch. You can use the same switch for Identity Server clustering and Access 
Gateway clustering, provided that you use different virtual IPs. The LB algorithm can be anything 
(hash/sticky bit), defined at the Real server levelFor configuration tips, see Section 9.2, 
“Configuration Tips for the L4 Switch,” on page 886. 


O Enable persistence (sticky) sessions on the L4 switch. Normally you define this at the virtual 
server level. 


O Create an Identity Server configuration for the cluster. You assign all Identity Servers to this 
configuration. 


Ħ See “Creating a Cluster Configuration” on page 67 for information about creating an Identity 
Server configuration. 


+ See “Assigning an Identity Server to a Cluster Configuration” on page 71 for information 
about assigning identity servers to configurations. 


O Ensure that the DNS name of the base URL for the cluster configuration resolves via DNS to the 
IP address of the L4 virtual IP address. The L4 switch balances the load between Identity 
Servers in the cluster. 


O Ensure that the L4 administration server using port 8080 has the following TCP ports open: 
+ 8443 (secure Administration Console) 
+ 7801 (for back-channel communication with cluster members). 
¢ 636 (for secure LDAP) 
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¢ 389 (for clear LDAP) 

¢ 524 (network control protocol on the L4 switch for server communication) 
The identity provider ports must also be open: 

+ 8080 (non-secure login) 

+ 8443 (secure login) 

+ 1443 (server communication) 


If you are using introductions (see Section 3.9.2, “Configuring General Provider Settings,” on 
page 177), you must configure the L4 switch to load balance on ports 8445 (identity provider) 
and 8446 (identity consumer). 


To enable session failover so users do not need to re-authenticate when an Identity Server goes 
down, see “Configuring Session Failover” on page 72. 


To modify the name of the cluster or edit communication details, see “Editing Cluster Details” on 
page 73. 


Configuring Session Failover 


When you set up an Identity Server cluster and add more than one Identity Server to the cluster, you 
have set up fault tolerance. This ensures that if one of Identity Servers goes down, users still have 
access to your site because the remaining Identity Server can be used for authentication. However, it 
does not’ provide session failover. If a user has authenticated to the failed Identity Server, that user is 
prompted to authenticate and the session information is lost. 


When you enable session failover and an Identity Server goes down, the user’s session information is 
preserved. Another peer server in the cluster re-creates the authoritative session information in the 
background. The user is not required to log in again and experiences no interruption of services. 


Prerequisites 


+ An Identity Server cluster with two or more Identity Servers. 
¢ Sufficient memory on Identity Servers to store additional authentication information. When an 


Identity Server is selected to be a failover peer, Identity Server stores about 1 KB of session 
information for each user authenticated on the other machine. 


Sufficient network bandwidth for the increased login traffic. Identity Server sends the session 
information to all Identity Servers that have been selected to be its failover peers. 


¢ All trusted Embedded Services Providers need to be configured to send the attributes used in 


Form Fill and Identity Injection policies at authentication. If you use any attributes other than the 
standard credential attributes in your contracts, you also need to send these attributes. To 
configure the attributes to send, click Devices > Identity Servers > Edit > Liberty > [Name of 
Service Provider] > Attributes. 


Configuring Session Failover 


1 Click Devices > Identity Servers. 
2 In the list of clusters and Identity Servers, click the name of an Identity Server cluster. 
3 Click the IDP Failover Peer Server Count, then select the number of failover peers you want 


each Identity Server to have. 
+ To disable this feature, select 0. 
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+ To enable this feature, select one or two less than the number of servers in your cluster. For 
example, if you have 4 servers in your clusters and you want to allow for one server being 
down for maintenance, select 3 (4-1=3). If you want to allow for the possibility of two servers 
being down, select 2 (4-2=2). 


If you have eight or more servers in your cluster, the formula 8-2=6 gives each server 6 
peers. This is probably more peers than you need for session failover. In a larger cluster, 
you must probably limit the number of peers to 2 or 3. If you select too many peers, your 
machines might require more memory to hold the session data and you might slow down 
your network with the additional traffic for session information. 


4 Click OK. 


How Failover Peers Are Selected 


The failover peers for an Identity Server are selected according to their proximity. Access Manager 
sorts the members of the cluster by their IP addresses and ranks them according to how close their IP 
addresses are to the server who needs to be assigned failover peers. It selects the closest peers for 
the assignment. For example, if a cluster member exists on the same subnet, that member is 
selected to be a failover peer before a peer that exists on a different subnet. 


Editing Cluster Details 


The Cluster Details page lets you manage the configuration’s cluster details, health, alerts, and 
statistics. 
1 Click Devices> Identity Servers. 
2 Click the name of the cluster configuration. 
3 Select from the following actions: 
Details: To modify the cluster name or its settings, click Edit, then continue with Step 4. 
Health: To view the health of the cluster, click the Health tab. 
Alerts: To view the alerts generated by members of the cluster, click the Alerts tab. 
Statistics: To view the statistics of the cluster members, click the Statistics tab. 
4 Modify the following fields as required: 


Cluster Communication Backchannel: Specify a communications channel over which the 
cluster members maintain the integrity of the cluster. For example, this TCP channel is used to 
detect new cluster members as they join the cluster, and to detect members that leave the 
cluster. A small percentage of this TCP traffic is used to help cluster members determine which 
cluster member would best handle a given request. This back channel must not be confused 
with the IP address/port over which cluster members provide proxy requests to peer cluster 
members. 


+ Port: Specify the TCP port of the cluster back channel on all of Identity Servers in the 
cluster. 7801 is the default TCP port. 


+ Encrypt: Encrypts the content of the messages that are sent between cluster members. 


Level Four Switch Port Translation: Configure the L4 switch to translate the port of the 
incoming request to a new port when the request is sent to a cluster member. Because the 
cluster members communicate with each other over the same IP address/port as the L4 switch, 
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the cluster implementation needs to know what that port is. The translated port is the port on the 
cluster members where other cluster members can contact it. This is the IP address and port 
where cluster members provide proxy requests to other cluster members. 


¢ Port translation is enabled on switch: Specify whether the port of the L4 switch is 
different from the port of the cluster member. For example, enable this option when the L4 
switch is using port 443 and Identity Server is using port 8443. 


+ Cluster member translated port: Specify the port of the cluster member. 


IDP Failover Peer Server Count: For configuration information, see “Configuring Session 
Failover” on page 72. 


5 Click OK, then update Identity Server when prompted. 


Removing a Server from a Cluster Configuration 


Removing an Identity Server from a configuration disassociates Identity Server from the cluster 
configuration. The configuration, however, remains intact and can be reassigned later or assigned to 
another server. 

1 Click Devices > Identity Servers. 

2 Select the server, then click Stop. Wait for the Health indicator to turn red. 

3 Select the server, then choose Actions > Remove from Cluster. 


For information about deleting an Identity Server, see Section 3.4.4, “Managing a Cluster of Identity 
Servers,” on page 66. 


IMPORTANT: When there are only two identity providers in a cluster, then introduce a new identity 
provider to the cluster and remove the other identity provider. 


Enabling and Disabling Protocols 


You can control which protocols can be used for authenticating with an Identity Server configuration. 
A protocol must be enabled and configured before users can use the protocol for authentication. For 
tight security, consider disabling the protocols that you are not going to use for authentication. 


When you disable a protocol, updating Identity Server configuration is not enough. You must stop and 
start Identity Server. 
1 Click Devices > Identity Servers > Edit. 
2 In the Enabled Protocols section, select the protocols to enable 
3 To disable a protocol, deselect it. 
4 Click OK. 
5 (Conditional) If you have enabled a protocol, update Identity Server. 
6 (Conditional) If you have disabled a protocol, stop and start Identity Server. 
6a Select Identity Server, then click Stop. 
6b When the health turns red, select Identity Server, then click Start. 
6c Repeat the process for each Identity Server in the cluster. 
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Modifying the Base URL 


When you configure an Identity Server, you must carefully determine your settings for the base URL, 
protocol, and domain. Changing the base URL invalidates the trust model and requires a re-import of 
the provider’s metadata, and a restart of the affected Embedded Service Providers. It also changes 
the ID of the provider and the URLs that others use for access. 


When you change the base URL of Identity Server, you invalidate the following trusted relationships: 
¢ The trusted relationships that Identity Server has established with each Access Manager device 
that has been configured to use Identity Server for authentication 


¢ The trusted relationship that each Access Manager device has established with Identity Server 
when Identity Server configuration was selected. 


¢ The trusted relationships that Identity Server has established with other service providers. 


The sessions of any logged-in users are destroyed and no user can log in and access protected 
resources until the trust relationships are reestablished. 


To modify the base URL and reestablish trust relationships: 
Click Devices > Identity Servers > Edit. 
Change the protocol, domain, port, and application settings, as necessary. 


Click OK. 
On Identity Servers page, click Update. 
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This re-creates the trusted Identity Server configuration to use the new base URL and metadata. 
5 Restart Tomcat on each Identity Server in the configuration: 
¢ Linux Identity Server: Specify one of the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
+ Windows Identity Server: Specify the following commands: 
net stop Tomcat7 net start Tomcat7 


6 For each Access Manager device configured to trust the configuration of this modified base URL, 
you must update the device so that the Embedded Service Provider trusts the new Identity 
Server configuration: 


Click Access Gateways, then click Update for any servers with a Status of Update. 


7 For each service provider you have configured to trust the configuration of this modified base 
URL, you must send them the new metadata and have them re-import it. 


For information about setting up SSL and changing an Identity Server from HTTP to HTTPS, see 
Chapter 17, “Enabling SSL Communication,” on page 977. 


Configuring Identity Server Global Options 


Global options are applicable for all Identity Servers in a cluster. 


NOTE: Access Manager 4.2 onwards, configuring the following options through files is deprecated. 
You must configure these option by using Administration Console. 
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Perform the following steps to configure Identity Server global options: 


1 Click Devices > Identity Servers > Edit > Options. 


2 Click New. 


3 Set the following properties based on your requirement: 


Property Type 


Allow Auth Policy Execution 


Cluster Cookie Domain 


Cluster Cookie Path 


DECODE RELAY STATE PARAM 


DELETE OLD SESSIONS OF USER 


HTTP ONLY CLUSTER COOKIE 


IS SAML2 POST INFLATE 


IS SAML2 POST SIGN RESPONSE 


Property Value 


Select false to disable Identity Server to execute authorization 
policies. 


The default value is true. 


For example, see “Executing Authorization Based Roles 
Policy During SAML 2.0 Service Provider Initiated Request” 
on page 480. 


Set this property to change the Domain attribute for Identity 
Server custer cookie. 


For example, see “Configuring X.509 Authentication to 
Provide Access Manager Error Message” on page 403. 


Set this property to change the Path attribute for Identity 
Server custer cookie. 


The default value is /nidp. 


For example, see “Configuring X.509 Authentication to 
Provide Access Manager Error Message” on page 403. 


Select true to enable the relay state URL decoding. 
The default value is false. 


Select true to enable Identity Server to delete the previous 
user sessions if the number of open sessions reaches the 
maximum limit of allowed sessions that you have specified in 
the Limit User Sessions field. 


The default value is false. 


Select false to disable the HTTPOnly flags for Identity Server 
cluster cookies. 


The default value is true. 


For example, see Section 30.3.11, “Enabling Secure or 
HTTPOnly Flags for Cluster Cookies,” on page 1208. 


Select true to enable Identity Server to receive deflated SAML 
2.0 POST messages from its trusted providers. 


The default value is false. 


You can configure post binding to be sent as a compressed 
option by configuring this property. For example, see the note 
in Step 4 on page 484. 


Select true to enable the identity provider to sign the entire 
SAML 2.0 response for all service providers. 
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Property Type 
LOGIN CSRF CHECK 


(This option is available in Access 
Manager 4.3 Service Pack 3 and later 
versions.) 


LOGOUT IDP SESSION ON IP CHANGE 


(Deprecated) 


RENAME SESSION ID 


SAML1X ATTRIBUTE MATCH BY NAME 


SECURE CLUSTER COOKIE 


Property Value 


Select true to enable Cross-Site Request Forgery (CSRF) 
check for the Password Class and TOTP Class. 


This is applicable for Access Manager default pages. If you 
have modified any page, you must add the CSRF token to the 
page. To add the CSRF token, add the following: 


JAVA: 
<% 


String sid = request.getParameter("sid")!=null ? 
request.getParameter (NIDPConstants.SID) 
(String)request.getAttribute(NIDPConstants.SID) 


1 


NIDPSessionData sData = 
NIDPContext .getNIDPContext().getSession(request 
).getSessionData(sid); 


boolean csrfCheckRequired = 
NIDPEdirConfigUtil.isConfigured(NIDPConfigkeys. 
LOGIN_CSRF_CHECK.name()) ? 
NIDPEdirConfigUtil.getValueAsBoolean(NIDPConfig 
Keys.LOGIN_CSRF_CHECK.name()) : false; 


%> 

HTML: 

<% if (csrfCheckRequired) { %> 
<input type="hidden" 

name="AntiCSRFToken" value=" 

<%=sData.getAntiCSRFToken( )%>"> 

<% } %> 


In Access Manager 4.3, this option has been merged with 
Advanced Session Assurance and called as Client IP. 


This option is listed as deprecated if you upgrade Access 
Manager from 4.2.x to 4.3. 


See Chapter 11, “Setting Up Advanced Session Assurance,” 
on page 931. 


Select false to prevent changing the session ID automatically. 
The default value is true. 


Select true to perform a strict check on the name space of the 
attributes received in assertion. 


For example, see Section 30.3.24, “SAML 1.1 Service 
Provider Re-requests for Authentication,” on page 1213. 


Select false to disable the secure flags for cluster cookies. 
The default value is true. 


For example, see Section 30.3.11, “Enabling Secure or 
HTTPOnly Flags for Cluster Cookies,” on page 1208. 
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Property Type 


STS CHANGE ISSUER 


STS OFFICE365 MULT! DOMAIN 
SUPPORT AUTO 


WSF SERVICES LIST 


WSFED ASSERTION VALIDITY 


WSTRUST AUTHORIZATION ALLOWED 
ACTAS VALUES 


Property Value 


Specify the value in this format: SPentityID: UPNDomain -> 
new Issuer|D. For example, 
urn:federation:MicrosoftOnline:support.namnetiq.in -> https:// 
namnetiq.in/nidp/wsfed/ 


In case of multiple child domains, add each parent domain 
and child domain separated by a comma. For example, if 
namnetiq.in is the parent domain and support.namnetiq.in 
and engineering.namnetiq.in are the child domains, specify 
the following entries: 


urn: federation:MicrosoftOnline:namnetiq.in -> 
https://namnetiq.in/nidp/wsfed/, 

urn: federation:MicrosoftOnline: support .namnetiq 
.in -> https://namnetiq.in/nidp/wsfed/, 

urn: federation: MicrosoftOnline: engineering.namn 
etiq.in -> https://namnetiq.com/nidp/wsfed/ 


For example, see “Configuring Federation for Multiple 
Domains that Include Child Domains” on page 628. 


Select true to enable users to access Office 365 services by 
using the Issuer URI specific to the domain they belong to. 


The default value is false. 


For example, see “Creating Multiple Domains in Office 365 
and Establishing Federation with Access Manager’ on 
page 626. 


Select full to enable users to access the Services page. 
Select 404 to return an HTTP 404 status code: Not Found. 
Select 403 to return an HTTP 403 status code: Forbidden. 
Select empty to return an empty services list. 

The default value is full. 


For example, see “Blocking Access to the WSDL Services 
Page” on page 427. 


Specify the assertion validity time in second for WS 
Federation Provider (SP) to accommodate clock skew 
between the service provider and SAML identity provider. 


The default value is 1800 seconds. 
For example, see “Assertion Validity Window” on page 555. 


Specify the user names who can perform ActAs operations. 
Allowed user names are the user accounts that the 
intermediate web service provider uses to authenticate with 
STS when sending a request with ActAs elements. 


You can specify more than one user name separated by a 
comma. 


For example, see “Adding Policy for ActAs and OnBehalfOf’ 
on page 571. 
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Property Type Property Value 


WSTRUST AUTHORIZATION ALLOWED Specify the user names who can perform OnBehalfOf 

ONBEHALF VALUES operations. Allowed user names are the user accounts that 
the intermediate web service provider uses to authenticate 
with STS when sending a request with OnBehalfOf elements. 


You can specify more than one user name separated by a 
comma. 


For example, see “Adding Policy for ActAs and OnBehalfOf’ 
on page 571. 


WSTRUST AUTHORIZATION ALLOWED Specify the user names who can perform both ActAs and 
VALUES OnBehalfOf operations. 


You can specify more than one user name separated by a 
comma. 


For example, see “Adding Policy for ActAs and OnBehalfOf’ 
on page 571. 


SESSION ASSURANCE USERAGENT _ Specify the user-agent string for that you want to disable the 
EXCLUDE LIST session validation. 


For example, see “Disabling Advanced Session Assurance 
for Identity Server’ on page 937. 


SESSION ASSURANCE USERAGENT _ Specify the user-agent REGEX for that you want to disable 
REGEX EXCLUDE LIST the session validation. 


For example, see “Disabling Advanced Session Assurance 
for Identity Server’ on page 937. 


SESSION ASSURANCE URL EXCLUDE Specify the URL for that you want to disable the session 
LIST validation. 


For example, see “Disabling Advanced Session Assurance 
for Identity Server’ on page 937. 


SESSION ASSURANCE URL REGEX Specify the URL REGEX for that you want to disable the 
EXCLUDE LIST session validation. 


For example, see “Disabling Advanced Session Assurance 
for Identity Server’ on page 937. 


SESSION ASSURANCE IDC COOKIE Specify the time in second till which Identity Server will accept 
GRACEPERIOD the old IDC cookie, after issuing a new cookie. The default 
value is 15 second. 


OTHER Specify Property Name and Property Value if you want to 
configure any other property. 


NAM_DFP_KEYS_ENFORCE_STRICT When Advanced Session Assurance is enabled, specify true 
to send session keys only the first time when the device 
information is fetched. Specify false to send session keys 
every time whenever device information is fetched. The 
default value is false. You can configure this property by 
clicking OTHER. 


4 Click OK > Apply. 
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3.5 Configuring Identity Server Shared Settings 


3.5.1 


The Shared Settings tab on Identity Servers page allows you to define the following shared settings: 


¢ Attribute sets: Sets of attributes that are exchangeable between identity and service providers. 


+ User matching expressions: The logic of the query to the user store for identification when an 
assertion is received from an identity provider. 


¢ Shared Secret names: Custom shared secret names that you want to be available when 
configuring policies. 


+ LDAP attributes: Custom LDAP attribute names that you want to be available when configuring 
policies. 

+ Authentication card images: Custom images that you can assign to authentication cards to 
uniquely identify an authentication procedure. 


+ Metadata Repositories: Import metadata of trusted providers. 
You can reuse these settings. These are available in any Identity Server cluster configuration. 
This section describes the following tasks: 


¢ Section 3.5.1, “Configuring Attribute Sets,” on page 80 

¢ Section 3.5.2, “Editing Attribute Sets,” on page 82 

¢ Section 3.5.3, “Configuring User Matching Expressions,” on page 83 

¢ Section 3.5.4, “Adding Custom Attributes,” on page 84 

¢ Section 3.5.5, “Adding Authentication Card Images,” on page 86 

¢ Section 3.5.6, “Creating an Image Set,” on page 86 

¢ Section 3.5.7, “Metadata Repositories,” on page 86 

¢ Section 3.5.8, “User Attribute Retrieval and Transformation,” on page 88 


¢ Section 3.5.9, “Specifying Advanced Authentication Server Details,” on page 105 


Configuring Attribute Sets 


The attributes you specify on Identity Server are used in attribute requests and responses, depending 
on whether you are configuring a service provider (request) or identity provider (response). Attribute 
sets provide a common naming scheme for the exchange. For example, an attribute set can map an 
LDAP attribute such as givenName to the equivalent remote name used at the service provider, 
which might be firstName. These shared attributes can then be used for policy enforcement, user 
identification, and data injection. 


Example 1: Attribute sets provide the centrally configurable means to map identity attributes between 
federation partners. When Access Manager Identity Server provides authenticated user information 
to a federated service provider such as Office 365, the attribute set determines what identity 
information is sent and available to Office 365 during and after authentication. The source of the 
identity data being sent can be the user's local LDAP directory or can be calculated dynamically. The 
identity data from external databases and secondary LDAP directories is achieved through Virtual 
Attributes. Virtual attributes are dynamically calculated attributes populated by the Attribute Retrieval 
and Transformation feature. See Section 3.5.8, “User Attribute Retrieval and Transformation,” on 
page 88. 


Example 2: You could have a web server application that requires a user’s e-mail address. You 
configure the web server to be a protected resource of Access Gateway, and you configure an 
Identity Injection policy to add the user’s email address to a custom HTTP header. When the user 
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accesses the protected resource, the value of the email attribute is retrieved. However, if you create 
an attribute set with this attribute, then assign it to be sent with the authentication response of 
Embedded Service Provider of Access Gateway, the value is cached at authentication and is 
immediately available. If you have multiple attributes that you are using in policies, obtaining the 
values in one LDAP request at authentication time can reduce the amount of LDAP traffic to your user 
store. 


You can define multiple attribute sets and assign them to different trusted relationships. You can also 
use the same attribute set for multiple trusted relationships. 


To create and configure an attribute set: 


1 Click Devices > Identity Server > Shared Settings > Attribute Sets > New. 
2 Specify the following fields: 
Set Name: Specify a name for identifying the attribute set. 


Select set to use as template: Select an existing attribute set that you have created, which you 
can use as a template for the new set, or select None. To modify an existing attribute set, select 
that set as a template. 


3 Click Next. 
4 To add an attribute to the set, click New. 
5 Specify the following fields: 
Specify the attribute. Select from the following: 


+ Local Attribute: Select an attribute from the list of all server profile, LDAP, shared secret 
attributes and virtual attributes. For example, you can select All Roles to use in role policies, 
which enables trusted providers to send role information in authentication assertions. Share 
secret attributes must be created before they can be added to an attribute set. For 
instructions, see “Creating Shared Secret Names” on page 84. 


¢ Constant: Specify a value that is constant for all users of this attribute set. The name of the 
attribute that is associated with this value is specified in the Remote Attribute field. 


Remote Attribute: Specify the name of the attribute defined at the external provider. The text for 
this field is case sensitive. 


+ A value is optional if you are mapping a local attribute. If you leave this field blank, the 
system sends an internal value that is recognized between Identity Servers. 


For a SAML 1.1 and SAML 2.0 identity consumer (service provider), a name identifier 
received in an assertion is automatically given a remote attribute name of 
saml:Nameldentifier. This allows the name identifier to be mapped to a profile attribute that 
can then be used in policy definitions. 


+ Avalue is required if you are mapping a constant. 


An attribute set with a constant is usually set up when Identity Server is acting as an identity 
provider for a SAML or Liberty service provider. The name must match the attribute name 
that the service provider is using. 


Remote namespace: Specify the namespace defined for the attribute by the remote system: 


+ If you are defining an attribute set for LDAP, select none. If you want a service provider to 
accept any namespace specified by an identity provider, select none. If you want an identity 
provider to use a default namespace, select none. The 
urn:oasis:names:tc:SAML:1.0:assertion value is sent as the default. 


+ If you are defining an attribute set for WS Federation, select the radio button next to the text 
box, then specify the following name in the text box. 


Setting Up a Basic Access Manager Configuration 81 


http://schemas.xmlsoap.org/claims 
+ If you want to specify a new namespace, select the radial button by the text box, then 
specify the name in the text box. 
Remote format: Select one of the following formats: 
+ unspecified: Indicates that the interpretation of the content is implementation-specific. 
¢ uri: Indicates that the interpretation of the content is application-specific. 


+ basic: Indicates that the content conforms to the xs:Name format as defined for attribute 
profiles. 


Attribute value encoding: Select one of the following encoding options: 
¢ Special characters encoded: Encodes only the special characters in the attribute value. 
+ Not encoded: Does not encode the attribute value. 
+ Entire value encoded: Encodes the entire attribute value. 
6 Click OK. 
The system displays the map settings on the Define Attributes page, as shown below: 


Identity Servers 


Create Attribute Set 
Step 2 of 2: Define attributes 

New | Delete 1 Item(s) 
. Local Attribute maps to Remote Attribute 

. Common First Name [Personal Profile] <--> firstname 


You can continue adding as many attributes as you need. 
7 Click Finish after you created the map. 


The system displays the map on the Attribute Sets page, as well as indicating whether it is in use 
by a provider. 


8 (Conditional) To configure a provider to use the attribute set, see Section 3.9.6, “Selecting 
Attributes for a Trusted Provider,” on page 187. 


3.5.2 Editing Attribute Sets 


You can edit attribute sets that have been created in the system. 


1 Click Devices > Identity Server > Shared Settings > Attribute Sets. 
2 Click the name of the attribute set that you want to edit. 
3 The system displays an attribute set page with the following tabs: 
General: Click to edit the name of the attribute set. 
Mapping: Click to edit the attribute map. 


NOTE: After editing the attribute mapping, verify the attribute set again in the trusted provider's 
list. Select the attributes from the Available list, and move them to the left side of the page. 
Update Identity Server. 


Usage: Displays where the attribute set is used. Informational only. 
4 Click OK, then click Close. 
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Configuring User Matching Expressions 


When a service provider receives an assertion from a trusted identity provider, the service provider 
tries to identify the user. The service provider can be configured to take one of the following actions: 


+ Accept that the assertion contains a valid user and authenticate the user locally with a temporary 
identity and account. As soon as the user logs out, the account and identity are destroyed. 


+ Use the attributes in the assertion to match a user in the local user store. When you want the 
service provider to take this action, you need to create a user matching expression. 


+ Use the attributes in the assertion to match a user in the local user store and when the match 
fails, create an account (called provisioning) for the user in the local user store of the service 
provider. When you want the service provider to take this action, you need to create a user 
matching expression. 


The user matching expression is used to format a query to the user store based on attributes 
received in the assertion from the identity provider. This query must return a match for one user. 


+ Ifthe query returns a match for multiple users, the request fails and the user is denied access. 


+ Ifthe query fails to find a match and you have selected provisioning, the service provider uses 
the attributes to create an account for this user in its user store. If you haven’t selected 
provisioning, the request fails and the user is denied access. 


The user matching expression defines the logic of the query. You must know the LDAP attributes that 
are used to name the users in the user store in order to create the user’s distinguished name and 
uniquely identify the users. 


For example, if the service provider user store uses the email attribute to identify users, the identity 
provider must be configured to send the email attribute. The service provider would use this attribute 
in a user matching expression to find the user in the user store. If a match is found, the user is 
granted access. If the user is not found, that attribute can be used to create an account for the user. 
The assertion must contain all the attributes that the user store requires to create an account. 


To create a user matching expression: 


Click Devices > Identity Servers > Shared Settings > User Matching Expressions. 
Click New, or click the name of an existing user matching expression. 
Specify a name for the user lookup expression. 
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Click the Add Attributes icon (plus sign), then select attributes to add to the logic group. (Use the 
Shift key to select several attributes.) 


5 Click OK. 
6 To add logic groups, click New Logic Group. 


The Type drop-down (AND or OR) applies only between groups. Attributes within a group are 
always the opposite of the type selection. For example, if the Type value is AND, the attributes 
within the group are OR. 


7 Click the Add Attributes icon (plus sign) to add attributes to the next logic group, then click OK. 
8 Click Finish. 


9 (Conditional) If you selected attributes from the Custom, Employee, or Personal profile, you 
need to enable the profile so that the attribute can be shared: 


9a Click Servers > Edit > Liberty > Web Service Provider. 
9b Select the profiles that need to be enabled, then click Enable. 
9c Click OK, then update Identity Server. 
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3.5.4 


3.5.4.1 


3.5.4.2 


Adding Custom Attributes 


You can add custom shared secret names or LDAP attribute names that you want to make available 
for selection when setting up policies. 

¢ Section 3.5.4.1, “Creating Shared Secret Names,” on page 84 

¢ Section 3.5.4.2, “Creating LDAP Attribute Names,” on page 84 


Creating Shared Secret Names 


The shared secret consists of a secret name and one or more secret entry names. You can create a 
secret name only, or a secret name and an entry name. For ease of use, the entry name must match 
the policy that uses it: 

¢ Fora Form Fill policy, the entry name must match a form field name. 

¢ For an Identity Injection policy, the entry name must match the Custom Header Name. 


¢ For an External Attributes policy, Secret Name must match the policy name and Secret Entry 
Name must match the attribute name configured while creating the policy. 


For example, if the policy name is fetchattr and attribute name configured in the policy is 
address, then Secret Name must be fetchattr and Secret Entry Name must be address. 


For more information about how to use shared secrets with policies, see Section 8.5.4, “Creating and 
Managing Shared Secrets,” on page 853. 


Identity Server needs to be configured to use shared secrets. For information about this process, see 
“Configuring a User Store for Secrets” on page 364. 


Shared secret names can be created either on the Custom Attributes page or in the associated policy 
that consumes them. 

1 Click Devices > Identity Servers > Shared Settings > Custom Attributes. 

2 Tocreate shared secret names, click New. 

3 Enter a new shared secret name and, optionally, a secret entry name. 

4 Click OK. 


5 (Optional) To create additional entries for the secret, click the name of the secret, click New, 
specify an entry name, then click OK. 


WARNING: Identity Server currently has no mechanism to determine whether a secret is being used 
by a policy. Before you delete a shared secret, you must ensure that it is not being used. 


Creating LDAP Attribute Names 


LDAP attributes are available for all policies. LDAP attribute names can be created either on the 
Custom Attributes page or in the associated policy that consumes them. The attribute names that you 
specify must match the name of an attribute of the user class in your LDAP user store. 
1 Click Devices > Identity Servers > Shared Settings > Custom Attributes. 
This list contains the attributes for the inetOrgPerson class. It is customizable. 
audio: Uses a u-law encoded sound file that is stored in the directory. 
businessCategory: Describes the kind of business performed by an organization. 


carLicense: Vehicle license or registration plate. 
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cn: The X.500 commonName attribute, which contains a name of an object. If the object 
corresponds to a person, it is typically the person’s full name. 


departmentNumber: Identifies a department within an organization. 


displayName: The preferred name of a person to be used when displaying entries. When 
displaying an entry, especially within a one-line summary list, it is useful to use this value. 
Because other attribute types such as cn are multivalued, an additional attribute type is needed. 


employeeNumber: Numerically identifies a person within an organization. 
employeeType: Identifies the type of employee. 

givenName: Identifies the person’s name that is not his or her surname or middle name. 
homePhone: Identifies a person by home phone. 

homePostalAddress: Identifies a person by home address. 


initials: Identifies a person by his or her initials. This attribute contains the initials of an 
individual, but not the surname. 


jpegPhoto: Stores one or more images of a person, in JPEG format. 


labeledURI: Uniform Resource Identifier with an optional label. The label describes the resource 
to which the URI points. 


mail: A user’s e-mail address. 

manager: Identifies a person as a manager. 

mobile: Specifies a mobile telephone number associated with a person. 

o: The name of an organization. 

pager: The pager telephone number for an object. 

photo: Specifies a photograph for an object. 

preferredLanguage: Indicates an individual’s preferred written or spoken language. 
roomNumber: The room number of an object. 

secretary: Specifies the secretary of a person. 

sn: The X.500 surname attribute, which contains the family name of a person. 
uid: User ID. 

userCertificate: An attribute stored and requested in the binary form. 


userPKCS12: A format to exchange personal identity information. Use this attribute when 
information is stored in a directory service. 


userSMIMECertificate: PKCS#7 SignedData used to support S/MIME. This value indicates that 
the content that is signed is ignored by consumers of userSMIMECertificate values. 


x500uniqueldentifier: Distinguishes between objects when a distinguished name has been 
reused. This is a different attribute type from both the uid and the uniqueldentifier type. 


To add a name: 
2a Click New. 


2b If you want the attribute to return raw data rather binary data, select 64-bit Encode Attribute 
Data. 


2c Click OK. 


To modify the 64-bit attribute data encoding, click an attribute’s check box, then click one of the 
following links: 
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3.9.9 


3.9.6 


3.5.7 


Set Encode: Specifies that LDAP returns a raw format of the attribute rather than binary format, 
which Access Manager encodes to base64, so that the protected resource understands the 
attribute. You might use base64 encoding if you use certificates that require raw bites rather than 
binary string format. 


Clear Encode: Deletes the 64-bit data encoding setting. 
4 Click Apply to save changes, then click the Servers tab to return to the Servers page. 


Adding Authentication Card Images 


Each authentication contract and managed card template must have a card associated with it. 


To add new images, the image files must be available from the workstation where you are 
authenticated to Administration Console. Images must fall within the size bounds of 60 pixels wide by 
45 pixels high through 200 pixels wide by 150 pixels high. To add a card image: 
1 Click Devices > Identity Servers > Shared Settings > Authentication Card Images. 
2 Click New. 
3 Fill in the following fields. 
Name: Specify a name for the image. 
Description: Describe the image and its purpose. 
File: Click Browse, locate the image file, then click Open. 


Locale: From the drop-down menu, select the language for the card or select All Locales if the 
card can be used with all languages. 


4 Click OK. 


5 If you did not specify All Locales for the Locale, continue with Section 3.5.6, “Creating an Image 
Set,” on page 86. 


Creating an Image Set 


You can create card images for specific locales as well as a default image for all locales. The images 
need to be placed in an image set that allows the browser to display the image associated with the 
requested locale. If the browser requests a locale for which you have not defined an image, the All 
Locales image is displayed. If an All Locales image is not available, the browser displays the Image 
not Available card. 
1 Click Devices > Identity Servers > Shared Settings > Authentication Card Images. 
2 Click the card image. 
3 To add an image to the set, click New, then fill in the following fields: 
File: Click Browse, then browse to the location of the file. 
Locale: Select the locale from the drop-down menu. 
4 Click OK. 


Metadata Repositories 


Large scale federations have more than 100+ identity and or service providers and it is a tedious task 
to establish bi-lateral relationships with Access Manager. You as an identity provider can now 
configure several identity and or service providers using a multi-entity metadata file available in a 
central repository. The identity and/or service providers become partners of a community which 
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3.5.7.1 


3.5.7.2 


maintains a single metadata file containing metadata of all the approved partners. The identity and or 
service providers submit their metadata which includes specifications of services offered (SAML 1.1 
and SAML 2.0) and any other information. This feature is available only for SAML 1.1 and SAML 2.0. 


For example, XYZ is an e-book store and several e-book stores, which are either identity or service 
providers are partner with it. XYZ maintains a single metadata file containing metadata of all the other 
stores. ABC an e-book identity provider wants to establish a federation with many other e-book 
stores. Hence, ABC partners with XYZ by sharing its metadata and XYZ in turn shares the metadata 
XML file. ABC imports the XML file available publicly on the internet (for example, http:// 
xyz.commonfederation.org/xyz-metadata.xml) and establishes trusts with others in the federation 
which includes XYZ’s trusted provider sites. 


Creating Metadata Repositories 


1 Click Devices > Identity Servers > Shared Settings > Metadata Repositories. 
2 Click New and fill in the following fields: 

Name: Enter the name of the metadata repository. 

Description: Enter the description of the metadata repository. 


Source: From the drop-down menu, select the source from which you want to import the 
metadata file. 


+ To specify the URL location of the XML file in the URL field, select Metadata URL. 
+ To specify the path of the XML file in the File field, select Metadata File. 
3 Click Finish. 


The details of the metadata such as the number of identity servers and service providers present 
in the metadata, and expiry date of the metadata are displayed. 


You can select the metadata repository and click Delete to delete the repository. If the metadata 
file is in use, you cannot delete it. Delete the trusted provider first and then delete the metadata 
file. 


4 Select All to see a list of entities. If the entity is supporting it the respective protocol will be 
checked. 


When the metadata repositories are imported, the entities available in the metadata repository can be 
assigned as trusted provider to any of the Identity Provider clusters. To create trusted providers, see 
Section 3.9.3, “Managing Trusted Providers,” on page 181. 


Reimporting Metadata Repositories 


You can reimport the metadata repository to get the updated XML. 


1 Click Devices > Identity Servers > Shared Settings > Metadata Repositories. 
2 Click on the metadata repository you created and click Reimport. 

3 Specify the URL location of the XML file in the URL field and click Next. 

4 The screen displays the following: 


New Entities added to the repositories: If the entities are updated or deleted and are 
assigned as TrustedProviders to an Identity Server cluster then Identity Server cluster name is 
displayed in brackets next to the entity ID. 


Entities Deleted from the repositories: If the entity is updated and is assigned as a trusted 
provider to an Identity Server cluster, that trusted provider will be updated. You must update 
Identity Server cluster for the changes to take effect. 
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Entities Updated in the repositories: If an entity is deleted and was assigned as trusted 
provider to an Identity Server cluster, then the link between the trusted provider and the 
metadata repository entity is deleted. 


NOTE: The corresponding trusted provider is not deleted. Delete the trusted provider manually. 


5 Click Finish to apply the changes. 


3.5.8 User Attribute Retrieval and Transformation 


With this release of Access Manager, you can retrieve an attribute from an external source and 
transform it before sending it in an assertion. The User Attribute Retrieval and Transformation feature 
enables you to retrieve attributes from a data source (any database or LDAP repositories) and 
transform them. This feature also allows you to transform user’s local attributes (LDAP attributes, 
Shared Secrets, and various profiles such as Personal Profile and Employee Profile). 


Virtual attributes can be used to generate dynamic data at runtime from the current values of the user 
attributes. 


The transformed attribute values are not stored in any persistent data stores. They are in the memory 
as part of user’s session. 

¢ Section 3.5.8.1, “How User Attribute Retrieval and Transformation Helps,” on page 88 

¢ Section 3.5.8.2, “Prerequisites,” on page 89 

¢ Section 3.5.8.3, “Limitations,” on page 89 

¢ Section 3.5.8.4, “Managing a Data Source,” on page 89 

¢ Section 3.5.8.5, “Managing an Attribute Source,” on page 92 

¢ Section 3.5.8.6, “Managing a Virtual Attribute,” on page 94 

¢ Section 3.5.8.7, “Sample JavaScripts with Examples,” on page 99 

¢ Section 3.5.8.8, “Troubleshooting User Attribute Retrieval and Transformation,” on page 104 
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User Attribute Retrieval and Transformation helps you to perform the following activities: 


+ Retrieve attribute values from external sources other than the configured user stores. The 
sources can be an external database or any external LDAP repository. 


+ Transform attribute values before they are sent as part of an assertion to a federated provider. 
For example, you can edit an attribute value before it is sent from identity provider to a service 
provider in a SAML 2.0 federation. You can also edit an attribute value sent from identity provider 
to Access Gateway used in policies. 


+ Transform the attribute value used in policies. For example, you can transform Identity Server 
role-based policies. 


User Attribute Retrieval and Transformation introduces the following configuration settings in Identity 
Server: 


¢ Data Source: An entity that holds configuration properties that help in connecting to an external 
data source. The properties of the data source can be defined in the data source user interface. 
A data source can be an LDAP repository or a SQL database. 
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3.5.8.2 


3.5.8.3 


3.5.8.4 


+ Attribute Source: Represents queries that fetch attributes from a data source. You can define 
either an LDAP search filter or a SQL query, based on the data source type. 


¢ Virtual Attribute: Helps you specify the attributes that must be transformed and in the way the 
transformations happen. A virtual attribute can transform multi- valued attributes. 


Prerequisites 


To perform complex user attribute transformations, you must have a basic understanding of 
JavaScript. To see sample JavaScripts with examples, see “Sample JavaScripts with Examples” on 
page 99. 


Limitations 
The following are the limitations of the User Attribute Retrieval and Transformation feature: 
¢ Multi-valued input parameters are not supported in the attribute source. If you input a multi- 


valued parameter, only one value is picked for the calculation. 


+ You cannot use the existing Identity server user stores directly as an attribute source. You must 
create a separate data source to use the user stores. 


+ You cannot edit or store any attribute value permanently in the existing LDAP attributes, shared 
secret attributes, or external database by using virtual attributes. 


+ The risk-based policies do not support virtual attributes. 
¢ OAuth configuration does not support virtual attributes. 


¢ Virtual attributes do not support modifications of attribute sources that contain binary data. Only 
string, boolean, integer, date, and numeric values from database are supported. 


¢ SSL communication with SQL and Oracle databases that are used by virtual attributes (data 
sources) is not supported. 


Managing a Data Source 


You can create, edit, or delete a data source. 


NOTE: You cannot delete a data source that is being used by an attribute source. 


This section discusses the following topics: 


¢ “Creating a Data Source” on page 89 
¢ “Editing a Data Source” on page 92 


Creating a Data Source 
To create a data source, perform the following steps: 


1 Click Devices > Identity Server > Shared Settings > Data Sources. 
2 Click + to add a data source. 
3 From the list, select one of the data sources: Database or LDAP. 
4 Specify the database connection properties. 
4a For Database 
MS SQL and Oracle databases are supported. 
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Field Description 


Database Name Specify the name of the database. 


Database Driver Select a driver from the list. The associated driver 
name is auto-populated. If you select Others 
(Unsupported), specify the driver name in the 
adjacent field. 


Max Connections Specify the maximum number of connections. By 
default, it is set to 20. 


Idle TimeOut Specify the idle timeout. By default, it is set to 
600000 milliseconds. You can set this value 
based on the server setting. For example, if the 
server timeout is 600000 milliseconds, then the 
timeout value must not exceed 600000. 


Connection TimeOut Specify the connection timeout. By default, it is 
set to 10000 milliseconds. You can set this value 
based on the server setting. 


Username Specify the username used to read from the 
database. 

Password Specify the password used to read from the 
database. 

Confirm Password Specify the password again. 

URL Specify the database URL based on the 


database driver selected. 


Based on the database type you select, you need to add the corresponding jars. 
4a1 For Oracle Database: 
4aia Download the JDBC connector for the Oracle database from Oracle.com. 
4aib Copy the JDBC connector jar to the following folder: 
On Windows 


e Administration Console: C:\Program Files 
(x86 ) \Novell\Tomcat \webapps\nps\WEB- INF\lib 


¢ Identity Server: C:\Program Files 
(x86) \Novell\Tomcat \webapps\nidp\WEB-INF\1lib 


On Linux 


¢ Administration Console: /opt/novell/nam/adminconsole/webapps/nps/ 
WEB-INF/1ib 


¢ Identity Server: /opt/novell/nam/idp/webapps/nidp/WEB- INF/1ib 
4aic Restart Administration Console and Identity Server. 
4a2 For Microsoft SQL Server: 
4a2a Download the JDBC connector for the SQL Server database from Microsoft.com. 
4a2b Copy the JDBC connector jar file to the following folder: 
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On Windows 


¢ Administration Console: C:\Program Files 
(x86) \Novell\Tomcat \webapps\nps\WEB-INF\1ib 


¢ Identity Server: C:\Program Files 
(x86) \Novell\Tomcat \webapps\nidp\WEB-INF\1lib 


On Linux 


e Administration Console: /opt/novell/nam/adminconsole/webapps/nps/ 


WEB- INF/lib 


¢ Identity Provider: /opt/novell/nam/idp/webapps/nidp/WEB-INF/lib 


4a2c Restart Administration Console and Identity Server. 


4b For LDAP: 


eDirectory and Active Directory are supported. 


NOTE: The SunONE directory is currently not supported. 


Field 


LDAP Name 


Username 


Password 


Confirm Password 


Directory Type 


Max Connections 


LDAP Operation TimeOut 


Idle Connection TimeOut 


IP Address 


Description 


Specify a display name for the LDAP database. 


Specify the username used to read from the 
database. 


Specify the password used to read from the 
database. 


Specify the password again. 


From the list, select the type of directory. If you 
select Others (Unsupported), specify a 

directory name in the adjacent field: sunonedir, 
custom1, custom2, custom3, custom4, others. 


Specify the maximum number of connections. By 
default, it is set to 20. 


Specify the LDAP operation timeout. By default, it 
is set to 15000 milliseconds. You can set this 
value based on the server setting. 


Specify the connection timeout. By default, it is 
set to 10000 milliseconds. You can set this value 
based on the server setting. For example, if the 
server timeout is 15000 milliseconds, then the 
LDAP timeout value must not exceed 15000. 


Specify the IP address of the LDAP directory. 
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Field Description 


Port Specify the port number. By default, it is 389. 


For a secure connection, select Use Secure 
LDAP Connection. The port number changes to 
636. 


You must import the trusted root if you select a 
secure connection. To import the trusted root, 
click Auto Import Trusted Root. The trusted 
certificate of the server will be imported to the 
Identity provider trust store. Update the Identity 
provider each time. 


Search Contexts The search context is used to locate users in the 
directory. If a user exists outside of the specified 
search context and its scope (or One level, 
Object or Subtree), Identity Server cannot find 
the user and the search fails. 


5 Test Connectivity: Click Test to test the data source connection after specifying the details. You 
can also view the error logs at the following locations: 


+ Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out 
+ Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.1log 


Editing a Data Source 


1 Click Devices > Identity Server > Shared Settings > Data Sources. 
2 Click the data source you want to modify. 
3 On the Edit Data Source page, modify the details as required. 


NOTE: If you change the IP address of the LDAP data source, then, you must import the trusted 
root of the updated server to Identity Server trust store. 


For more information about the fields on this page, see “Creating a Data Source” on page 89. 
4 Click OK. 
5 Update Identity Server. 


IMPORTANT: You must update Identity Server every time you edit the properties of a data source 
that is being used by an attribute source and the attribute source in turn, being used by the virtual 
attribute. 


3.5.8.5 Managing an Attribute Source 


You can create, edit, or delete an attribute source. 


NOTE: You cannot delete an attribute source that is being used by a virtual attribute. 


This section discusses the following topics: 


¢ “Creating an Attribute Source” on page 93 
¢ “Editing an Attribute Source” on page 94 
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Creating an Attribute Source 


Click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source. 
Click + to add an attribute source. 

Specify an attribute source Name. 

Specify the description of the attribute source. 

From the list, select the data source. 


on fF OO N RP 


Click Step 1: Provide input parameters. 


6a Name: Specify a name for the attribute. You must specify the same name in the query field. 
The default value is %P1%. 


6b Parameter Value: Select an attribute from the list. The available options are: Server profile, 
LDAP, and shared secret attributes. 


6c Click Show / Add Test Values? to display the test value field. Specify a value in the Test 
value field. 


To provide additional parameter values, click +. 


NOTE: The attribute source does not support multi-valued inputs. If you input multiple values, 
only one value is picked for the calculation. 


7 Click Step 2: Provide query and output parameters. 
For one attribute source, you can provide only one output parameter. 


7a Filter / Query: Specify an LDAP filter or a database query. The query must use the input 
details specified in the Step 1: Provide input parameters section. 


7b Filter / Query Output Parameters: Specify a name for the filter / query output. To add 
multiple output parameters, click Add. 


+ In the case of an LDAP filter, you need to specify the exact name of the attribute that 
you want to fetch. 


+ In the case of a database query, you can specify an alias for the attribute fetched. The 
order of the output parameters must match the sequence in which they are specified in 
the database query. 


7c Test: To test the input values based on the filter and output parameters, click Test. For 
security reasons, you are prompted to enter the data source credentials. The Test Result 
window displays the status along with the test results. You can also view the error logs at 
the following locations: 


+ Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out 
+ Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout . log 
LDAP Scenario: 


Consider a scenario where you want to fetch an email address from the external LDAP directory 
for which the user’s LDAP attribute (from the external LDAP directory) UID matches with the 
local LDAP attribute cn. 


To configure this, perform the following steps: 


1. In Step 1: Provide input parameters, select LDAP attribute: cn as a parameter value. Add 
input parameter %P1% and map it to the LDAP attribute. 
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2. In Step 2: Provide filter and output parameters: 
a. Specify the following query: (&(objectclass=* ) (uid=%P1%) ) 


b. Specify the filter output name as email. email is the alias name given for the column 
email. 


3. To test this configuration: 


a. In Step 1: Provide input parameters, select Show / Add Test Values? and provide the 
test value as admin. 


b. In Step 2: Provide filter and output parameters: Click Test. Enter the data source 
credentials. 


The test results return the email address stored in the directory: admin123@example.com. 
Database Scenario: 


Consider a scenario where you want to fetch an email address from the database for which the 
user’s name matches with the local LDAP attribute cn. 


1. In Step 1: Provide input parameters, select LDAP attribute: cn as a parameter value. 
2. In Step 2: Provide query and output parameters: 


a. Specify the following query: select email from Emp where name = '%P1%' (email 
and name is the column name and Emp is the table name) 


b. Specify the filter output name as mail (mail is the alias name given for the column 
email) 


3. To test this configuration: 


a. In Step 1: Provide input parameters, select Show / Add Test Values? and provide a 
test value that represents a record in the column of the table. 


b. In Step 2: Provide query and output parameters: Click Test. Enter the data source 
credentials. 


The test results return the email address stored in the database: admin123@example.com. 


Editing an Attribute Source 
To edit the properties of an attribute source, perform the following steps: 


1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source. 
2 Click the attribute source you want to modify. 
3 On the Edit Attribute Source page, modify the details as required. 


For more information about the fields on this page, see “Creating an Attribute Source” on 
page 93. 


4 Click OK. Update Identity Server. 


IMPORTANT: If the attribute source is being used by a virtual attribute, you need to update Identity 
Server every time you edit the properties of an attribute source. 


3.5.8.6 Managing a Virtual Attribute 


You can create, edit, or delete a virtual attribute. 


NOTE: You cannot delete a virtual attribute that is being used by an attribute set. Also, before 
deleting a virtual attribute, ensure that it is not being used by a policy. 
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This section discusses the following topics: 


¢ “Creating a Virtual Attribute” on page 95 
¢ “Editing a Virtual Attribute” on page 99 


Creating a Virtual Attribute 
You can create a virtual attribute from an attribute source and an external data source. 


1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute. 
2 Click + to create a virtual attribute. 

3 Specify a name for the virtual attribute. 

4 Enter the description. 

5 Click Step 1: Provide input > parameters. 


5a Name: Specify a name for the attribute. If you use advanced JavaScript option, then, you 
need to specify the same name in the advanced JavaScript field. The default value is P1. 


5b Parameter Value: Select an attribute from the list. In addition to Server profile, LDAP, and 
shared secret attributes, attribute sources are also listed. To specify additional values, click 
+, 


NOTE: If an attribute source returns a null or an empty value, then the corresponding input 
parameter takes an empty string value. 


5c Click Show / Add Test Values? to display the test value field. Click + to add a test value. 
Click the edit icon to edit the test value. Click the delete icon to delete the test value. 


6 Click Step 2: Provide a modification function. 


6a Select a function: From the list, select a function. The corresponding JavaScript is 
displayed in the Script field. To view it, expand the script. You can further customize these 
scripts and use them in the Advanced JavaScript field. 


The following table lists the pre-defined JavaScript functions along with examples: 


Function Description Example: Pre-Defined 
Functions 
To UpperCase Converts the input value to If P1=alice, then the result 


upper case.This function works | displays ALICE. 
on arrays and single-valued 
input. It uses the following 
JavaScript function: 
toUpperCase() 


Works only on one input 
parameter that is selected in 
Step 1: Provide input 
parameters 
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Function 


To LowerCase 


Description 


Converts the input value to 
lower case. This function works 
on arrays and single-valued 
input. It uses the following 
JavaScript function: 
toLowerCase() 


Works only on one input 
parameter that is selected in 
Step 1: Provide input 
parameters 


Example: Pre-Defined 
Functions 


If P1=ALICE, then the result 
displays alice. 


Remove Substring 


Removes a substring from all 
instances of the input value. 
This function does not remove 
a substring from the global 
option.This function works on 
arrays and single-valued input. 
It uses the following JavaScript 
function: split() and join() 


Works only on one input 
parameter that is selected in 
Step 1: Provide input 
parameters 


If P1=a@microfocus.com 


Remove=@microfocus, then 
the result is a.com. 


Find and Replace 


Finds and replaces a string 
from all instances of the input 
value. 


Works only on one input 
parameter that is selected in 
Step 1: Provide input 
parameters 


If P1=abcde 
Find=e 


Replace=a, then the result 
displays abcda 


Regex Replace 


Finds and replaces a substring 
from all instances of the input 
value by using a regular 
expression. 


For example, to search /, you 
must escape it first using \. 
Use the following syntax: /\// 


This function works on arrays 
and single-valued input. It uses 
the following JavaScript 
functions: replace() 


Works only on one input 
parameter that is selected in 
Step 1: Provide input 
parameters 
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If P1=bob@novell.com 
Find=@novell.com 
Replace=@microfocus.com 


The result displays: 
bob@microfocus.com 


Function 


Find Subset by Regex 


Description 


Use this function if an input is 
multi-valued and you want a 
subset of values from it, 
satisfying a particular condition 
by using a regular 
expression. This function works 
on arrays and single-valued 
input. It uses the following 
JavaScript function: 
replace() 


Works only on one input 
parameter that is selected in 
Step 1: Provide input 
parameters 


Example: Pre-Defined 
Functions 


If 


P1="a@novell.com, 
b@novell.com,c 
@microfocus.com, 
d@microfocushr.com” 


regex= /microfocus/ 
Then, the result displays: 


c@microfocus.com, 
d@microfocushr.com 


Concatenate Values in a 
Parameter 


Concatenates multiple values 
of a multi-valued input. You 
must add a separator between 
the values that you want to 
concatenate 


If P1=abc, def 
Separator=+ 


Then, the result displays: 


+ 
Works only on one input aber deh 
parameter that is selected in 
Step 1: Provide input 
parameters 
Concatenate Multiple Concatenates multiple input If P1=abc, def 


Parameters 


parameter values, where each 
input parameter can be multi- 
valued input. You must add a 
separator between the values 
that you want to concatenate 


and P2=123, 456 
Parameter Separator=+ 
Multi value Separator=: 


Then, the result displays 
abc:def+123:456 


Advanced JavaScript 


NOTE 


Specify a customized 
JavaScript In this field. You 
need to create a JavaScript 
function with name “main” and 
specify the code in it. You can 
write your custom code or you 
can also copy the existing pre- 
defined code.You can also call 
multiple functions in the “main” 
function. 


See the “Sample JavaScripts 
with Examples” on page 99. 


+ After JavaScript processing, if the output is a null value, then the value of the virtual 


attribute is empty. 


+ The pre-defined function can handle both single-valued and multi-valued inputs. If the 
input is multi-valued, then pre-defined function is applied on each of the values. 
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Advanced JavaScript: 
Sample JavaScript: 


function main(P1, P2) 


{ 
//some logic 
//you can call yourFunction(name) and use its return value 
return some value; 

} 


function yourFunction(name) 


//some code 
//return some value; 


} 


In case of advanced JavaScript, the input parameter name in the main function of the 
JavaScript must match the input parameter name specified in the Step 1: Provide input 
parameters section. The return value can be a single value or an array. 


When the input is multi-valued, it is passed as an array to the main function. 


When Identity Server computes the value of a virtual attribute, it calls a function named 
“main” that is available in the script provided for it. The value (single value or array) returned 
by main is the value of the virtual attribute. 


For example:Consider a scenario where P1 contains bmw and nissan, you can use the 
JavaScript instanceof function to check if the input is single-valued or multi-valued. If it is 
multi-valued, then JavaScript iterates over the values P1=['bmw', 'nissan'] 


function main (P1){ 
if( P1 instanceof Array) { 
var a =P1[0] //will assign 'bmw' value to variable a 
//do something 
} 
} 


The following code checks if an input parameter has a value, is empty or undefined: 


function main(P1){ 
if (hasNoValue(P1) ) 
// do something 
return something; 


} 
function hasNoValue(P1){ 
if(P1 == null || (typeof P1 == 'undefined') || P1.trim().length == 0) 
return true; 
else 
return false; 
} 


6b Test: To test the input values based on the modification function, click Test. To test multi- 
valued inputs, click the + button. 


For example, if an attribute mail has two values: abc@example . com and def@example . com, 
then to test them, click the + button twice. In each field, add the values separately. 


The Test Result window displays the status along with the test results. You can view the 
error logs at the following locations: 


¢ Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out 
¢ Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.log 
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7 Click OK. 
8 Update Identity Server. 


Editing a Virtual Attribute 


1 Click Devices > Identity Server > Shared Settings > Virtual Attributes. 
2 Click the virtual attribute you want to modify. 
3 On the Edit Virtual Attribute page, modify the details as required. 
For more information about the fields on this page, see “Creating a Virtual Attribute” on page 95. 
4 Click OK. Update Identity Server. 


IMPORTANT: You must update Identity Server every time you edit the properties of a virtual attribute. 


Sample JavaScripts with Examples 


The following section provides sample JavaScripts with examples. These are used in the Virtual 
Attributes section. 


Use Case 1: 


Consider a scenario where a service provider wants to append PID with an attribute partnerld. For 
example: PID: P1. 


To achieve this, fetch a user's partnerld by using their existing “givenName” LDAP attribute (available 
from the logged in user store) from the external LDAP repository. Now, and add a string “PID:” to it. 
Later, send the value in web servers through the Identity injection policy. 


Solution: The solution is as follow: 
Creating a Data Source: 
1 Configure an LDAP data source with name “dsLdap’”. Specify the connection properties. Test the 


connection. 


2 Import the secure LDAP certificate to Identity Server trust store using the create Data Source 
screen. 


3 Click Update All to update Identity Servers. 
Creating an Attribute Source: 
1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Attribute Source. 
Create an attribute source with name “dsLdapAttrSrc’”. 
2 Select data source name “dsLdap”. 
3 Add input parameter %P1%. Map it to the LDAP attribute: givenName. 
4 Add a Filter: name=%P1%. 
5 Add output parameter: partnerID 
6 Test Filter: Test the input values. 
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Creating a Virtual Attribute: 


1 Click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute. Create 
a virtual attribute with name “partnerID”. 


2 Add input parameter P1. Map it to dsLdapAttrSrc:partnerID (the attribute source that you 
created in Step 1 of the creating an Attribute Source section). 


3 In Step 2: Provide query and output parameters, specify the following script: 


function main(P1){ 
return "PID:"+P1; 
} 


4 Test the script. The results return: PID: P1. For example, if partnerlD=part123, then, the test 
result is PID:part123. 


5 Update Identity Server. 
6 Use it in the Identity injection policy. 


Use Case 2: 


Consider a scenario where, if the authenticated user is a manager and has administrator rights to a 
protected human resource application, then, when he accesses this application, his roles must be 
passed to the application. 


In this scenario, the manager has a local LDAP attribute isManager and has roles of a recruiter and 
an employee. He also has a local LDAP attribute groupmembership, which contains the string 
"admins" (for example: adminsRecruitmentDep, adminsPoliciesDep ). 


Solution: 
Create a virtual attribute: App1Admin. 
In Step1: Provide input parameters, select the following input parameters: 


+ P1:is mapped to LDAP attribute isManager 
+ P2: is mapped to LDAP attribute groupmembership 
+ P3: is mapped to LDAP attribute role value 


Use the following code in the Step 2: Provide a modification function > Advanced Javascript: 


function main(P1, P2, P3){ 


if(P1 == 'true' && (/admins/i.test(P2) == true)){ 
return P3; 
}else{ 


return 'NA'; 


} 
} 


To test the JavaScript, click the + and add multiple test values. Specify the following test values: 


+ P1: true 
+ P2: adminsRecruitmentDep 
¢ P3: recruiter, employee 


Output: The output is a multi-valued virtual attribute recruiter, employee. 


Explanation: In the function, /admins/i.test(P2) == true, /admins/i is a regular expression and test is a 
JavaScript in-built function. This function tests the regular expression in the string passed as the input 
parameter. The function returns true if the string contains the required pattern. 
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Consider a scenario where, an Access Manager user wants to access Amazon Web Services (AWS). 
AWS has multiple roles and each AWS role can have various access rights or policies assigned to it. 
Based on the level of access, you can access authorized Amazon services. This information about 
roles must be passed dynamically by Access Manager to AWS to provide single sign-on to the 
Access Manager user. 


For more information about AWS configuration, see Section 5.2.12, “Integrating Amazon Web 
Services with Access Manager,” on page 620. 


In this scenario, you have a constant value created using <Role ARN, Trusted SAML Provider ARN> 
mapped to Remote AWS attribute Role (this value is the AWS format). 


Let suppose you have configured the following roles in AWS: admin, finance. The role ARNs are: 


+ For admin: arn: aws: iam: :638116851885: role/admin 


+ For finance: arn: aws: iam: :638116851885: role/finance 


For admin role, pass the following: arn: aws: iam: :638116851885: role/ 
admin, arn: aws: iam: :638116851885: saml-provider/NAMIDP 


For finance role, pass the following: arn: aws: iam: :638116851885: role/ 
finance, arn: aws: iam: :638116851885: saml-provider/NAMIDP 


In this example, to dynamically generate the AWS role, use the LDAP attribute Department Name in 
the user store. For the admin user, the department name is admin. For the finance user, the 
department name is finance. To make department name available as an LDAP attribute, ensure that 
you enable personal profile. Click Identity Servers > Edit > Liberty > Web Service Provider. 


Solution: 
Create a virtual attribute with the following information: 


When the user logs in, the department name (finance) is fetched for the respective user and 
appended with the constant value of the role ARN. This value is then concatenated with the trusted 
SAML provider ARN in the following format: arn: aws: iam: :638116851885: role/ 

admin, arn: aws: iam: :638116851885: saml-provider/NAMIDP 


Map this virtual attribute with the AWS Remote Attribute role. 


In Step1: Provide input parameters, select P1 parameter value as Department Name (Personal 
Profile). 


Use the following code in the Step 2: Provide a modification function > Advanced Javascript: 


function main(P1){ 
var role_arn='arn:aws: iam: :638116851885:role/' 
var provider_arn=',arn:aws: iam: :638116851885: saml-provider/MyIDP_184-142'; 
var aws_role; 
aws_role = role_arn+Pi+provider_arn; 
return aws_role; 


} 


To test the JavaScript, click the + and add multiple test values. Specify the test value of P1: finance. 


Output: arn: aws: iam: :638116851885: role/finance, arn: aws:iam: :638116851885: sam1 - 
provider/NAMIDP. 


Use Case 4: 
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Consider a scenario where, for a service provider - cloudsp, you want to send the groups associated 
with the user to the service provider. However, you only want to send the groups relevant to that 
service, and not the complete group DN. Check for a function that checks if the group cn starts with 
“cloudsp”. If available, send it to the group cn. 


In this scenario, the cn of the groups relevant to cloudsp start with “cloudsp” ( for example: 
"cn=cloudspa,ou=group,o=mycompany") So, when a cloudsp user authenticates at the Identity 
provider, you need to extract all the cn values from the local LDAP attribute groupMembership and 
filter only those names starting with cloudsp and send it in assertion to cloudsp. 


Solution: 
In Step1: Provide input parameters, select P1 as an attribute which has the groups. 
Use the following code in the Step 2: Provide a modification function > Advanced Javascript: 


function main( P1 ){ 
return mapGroups(P1); 
} 


function mapGroups(attribute){ 
var result = []; 
if (attribute instanceof Array){ 
var j =0; 
for(var i=0; i<attribute.length; i++){ 
var grp = checkGroup(attribute[i]); 
if( grp != 'NA') 
result[j++] = grp; 


} 
}else{ 
var grp = checkGroup(attribute); 
if( grp != 'NA') 
result[0] = grp; 
} 


return result; 


} 


function checkGroup(group){ 
if(/4cn=cloudsp.*,/.test(group) == true){ 
var startindex = 3;// it starts with cn 
var endindex = group.indexof(","); 
return group.substring( startindex, endindex); 
yelse 
return 'NA'; 


} 


To test the JavaScript, click the + and add multiple test values. Specify the test values: 


cn=cloudspgroupa, ou=group, o=mycompany cn=cloudspgroupb, ou=group, o=mycompany 
cn=cloudspgroupk, ou=group, o=mycompany 


cn=testgroupa, ou=group, o=mycompany 
Output: 


cloudspgroupa 
cloudspgroupb 
cloudspgroupk 


Explanation: 
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The JavaScript in-built string function substring is used to extract the cn value from the group./ 
Acn=cloudsp.”,/.test(group) is a regular expression which matches a string that starts with cloudsp. It 
has 0 or more characters followed by a comma (,) 


Use Case 5: (utility function reuse test case)Consider a scenario where, the Identity provider roles 
are in the format companyX:rolename, but a service provider abc wants the roles in the following 
format: rolename and is in upper case. 


To achieve this, remove 'companyxX:' from each role and convert each of them into upper case for 
sending them to the protected web server. Each role is specified as companyX:rolename. 


For example: companyX:admin, companyX:guest. 

Solution: 

In Step 1: Provide input parameters, select P1: All Roles. 

Use the following code in the Step 2: Provide a modification function > Advanced Javascript: 
Copy the JavaScript from the following pre-defined functions: Remove Substring and To upperCase. 
Remove Substring function: 


function findReplace(attribute, findString, replaceString) { 
var result; 
if(attribute instanceof Array){ 
result = []; 
for(var i=0; i<attribute.length; i++){ 
result[i] =attribute[i].split(findString).join(replaceString) ; 


} 
}else{ 

result = attribute.split(findString).join(replaceString); 
} 


return result; 


} 


To upperCase function: 


function convertToUpperCase (attribute){ 
var result ; 
if (attribute instanceof Array){ 
result = []; 
for(var i=0; i<attribute.length; i++) 
result[i] = attribute[i].toUpperCase(); 
}else{ 
result = attribute.toUpperCase(); 
} 


return result; 


} 


Now, customize the code. In the Substring to remove parameter for findReplace (), specify 
companyx: 
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function main(P1) { 
return convertToUpperCase(findReplace (P1, 'CompanyX:')); 
} 


function findReplace(attribute, findString, replaceString){ 
var result ; 
if(attribute instanceof Array){ 
result = []; 
for(var i=0; i<attribute.length; i++){ 
result[i] =attribute[i].split(findString).join(replaceString); 


}else{ 
result = attribute.split(findString).join(replaceString); 
} 


return result; 


} 


function convertToUpperCase (attribute){ 
var result; 
if (attribute instanceof Array){ 
result = []; 
for(var i=0; i<attribute.length; i++) 
result[i] = attribute[i].toUpperCase(); 
}else{ 
result = attribute.toUpperCase(); 
} 


return result; 


} 


To test the JavaScript, add the following test values in P1: 'companyX:admin', 
‘companyX:guest'.Output: ADMIN, GUEST. 


Use Case 6: 


Consider a scenario where you do not want to modify an attribute value that is retrieved from an 
external source. To send the same attribute value in the assertion to a federated provider or in the 
policies, perform the following: 


Click Devices > Identity Server > Shared Settings > Virtual Attributes > Virtual Attribute. 


In Step1: Provide input parameters, select P1 and map it to an attribute retrieved from an external 
source. 


In Step 2: Provide a modification function, select Advanced JavaScript and specify the following 
script: 


function main(P1) { 
return P1; 
} 
Test the script. The results returns the value of the attribute source specified as P1. 


Update Identity Server. 


Troubleshooting User Attribute Retrieval and Transformation 


For troubleshooting information, see Section 30.13, “Troubleshooting User Attribute Retrieval and 
Transformation,” on page 1266. 
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3.6 


3.6.1 


Specifying Advanced Authentication Server Details 


To specify the Advanced Authentication server details, perform the following: 


1 Click Devices > Identity Server > Shared Settings > Advanced Authentication. Specify the 
Advanced Authentication server details. 


2 Proceed with Section 5.3.3, “NetIQ Advanced Authentication,” on page 648 to create Advanced 
Authentication classes. 


Configuring Access Gateway 


The basic Access Gateway configuration procedures consists of the following tasks: 


¢ Section 3.6.1, “Configuring a Reverse Proxy,” on page 105 

¢ Section 3.6.2, “Configuring a Public Protected Resource,” on page 107 

¢ Section 3.6.3, “Configuring Access Gateway for Authentication,” on page 108 
¢ Section 3.6.4, “Setting Up Policies,” on page 110 


Configuring a Reverse Proxy 


You can protect your web services by creating a reverse proxy. A reverse proxy acts as the front end 
to your web servers in your DMZ or on your intranet. It off-loads frequent requests, thereby freeing up 
bandwidth and web server connections. It also increases security because the IP addresses and 
DNS names of your web servers are hidden from the Internet. A reverse proxy can be configured to 
protect one or more proxy services. 


To create a reverse proxy, you must create at least one proxy service with a protected resource. You 
must supply a name for each of these components. Reverse proxy names and proxy service names 
must be unique to Access Gateway because they are configured for global services such as IP 
addresses and TCP ports. For example, if you have a reverse proxy named products and another 
reverse proxy named library, only one of these reverse proxies can have a proxy service named 
corporate. 


Protected resource names need to be unique to the proxy service, but they don’t need to be unique to 
Access Gateway because they are always accessed through their proxy service. For example, if you 
have a proxy service named account and a proxy service named sales, they both can have a 
protected resource named public. 
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What You Need To Know 


Name of Identity Server cluster 


Example Your Value 


idp-corporate 


DNS name of Access Gateway mytest.com 
Web server information 
IP address 10.15.70.21 
DNS name mywebserver.com 
Names you need to create 
Reverse proxy name mycompany 
Proxy service name company 
Protected resource name public 


This first reverse proxy is used for authentication. You need to configure the proxy service to use the 
DNS name of Access Gateway as its Published DNS Name, and the web server and the resource on 
that web server need to point to the page you want displayed to the users when they first access your 
web site. You can use Access Gateway configuration options to allow this first page to be a public site 
with no authentication required until the users access the links on the page, or you can require 
authentication on this first page. Complete the following configuration steps to first configure a 
protected resource as a public resource and then to modify the configuration to require 
authentication. 


1 Click Devices > Access Gateways, Edit > Reverse Proxy / Authentication. 


In Identity Server Cluster option, select the configuration you have assigned to Identity Server. 


This sets up the trust relationship between Access Gateway and Identity Server that is used for 
authentication. 


3 In Reverse Proxy List, click New, specify a display name for the reverse proxy, then click OK. 
4 Enable a listening address. 


Listening Address(es): A list of available IP addresses. If the server has only one IP address, 
only one is displayed and it is automatically selected. If the server has multiple addresses, you 
can select one or more IP addresses to enable. You must enable at least one address. 


TCP Listen Options: Options for configuring how requests are handled. You cannot set up 
listening options until you create a proxy service. 


Ignore the SSL configuration options. 


This basic configuration does not set up SSL. For SSL information, see Chapter 17, “Enabling 
SSL Communication,” on page 977. 


Configure a listening port. 
Non-Secure Port: Select 80 that is the default port for HTTP. 


Secure Port: This is the HTTPS listening port. This port is unused and cannot be configured 
until you enable SSL. 


7 In Proxy Service List, click New. 


8 Specify the following details: 
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Field Description 


Proxy Service Name A display name for the proxy service. 


Published DNS Name The DNS name you want the public to use to access your site. For 
this first proxy server, the DNS name must resolve to Access 
Gateway IP address that you selected as the listening address. For 
the example in Figure 3-2 on page 58, this name would be 
www.mytest.com. 


Web Server IP Address The IP address of your web server. This is the web server with 
content that you want to share with authorized users and protect 
from others. In Figure 3-2 on page 58, this is Server 4, whose IP 
address is 10.15.70.21. 


Host Header The name you want to send in the HTTP header to the web server. 
This can either be the published DNS Name (the Forward 
Received Host Name option) or the DNS name of the web Server 
(the Web Server Host Name option). 


Web Server Host Name The DNS name that Access Gateway must forward to the web 
server. This option is not available if you select Forward Received 
Host Name for the Host Header option. The name you use 
depends upon how you have set up the web server. If your web 
server has been configured to verify that the host name in the 
header matches its name, you need to specify that name here. In 
Figure 3-2 on page 58, the Web Server Host Name is 
mywebserver.com. 


9 Click OK. 
10 Continue with Section 3.6.2, “Configuring a Public Protected Resource,” on page 107. 


Configuring a Public Protected Resource 


The first protected resource in discussed in this configuration is configured to be a public resource. 
For information on how to set up authentication for a protected resource, see Section 3.6.3, 
“Configuring Access Gateway for Authentication,” on page 108. 

1 In Proxy Service List, click [Name of Proxy Service] > Protected Resources. 

2 In Protected Resource List, click New, specify a name for the resource, and click OK. 

3 In the Contract field, select None. 

The Contract field must be set to None. This is makes this resource a public resource. 
4 Configure URL Path List. 


The default path is /*, which allows access to everything on the web server. Modify this if you 
need to restrict access to a specific directory on your web server. 


+ To delete the default path, select the check box next to the path, then click Delete. 
¢ To edit a path in the list, click the path, modify it, then click OK. 


+ To add a path, click New, specify the path, then click OK. For example, to allow access to 
the pages in the public directory on the web server, specify the following path: 


/public/* 
5 Click OK. 
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6 In the Protected Resource List, verify that the protected resource you created is enabled, then 
click OK. 


7 Click Devices > Access Gateways. 
8 Click Update > OK. 


The system sends configuration changes to the server and writes the configuration to the 
configuration data store. When the update has completed successfully, the server returns the 
status of Current. 


To save the changes to the configuration store without applying them, do not click Update. 
Instead, click Edit. If you have pending configuration settings, the OK button is active, and the 
configuration page indicates which services will be updated. Click OK to save these changes to 
the configuration store. The changes are not applied until you Update on Access Gateways 
page. 

9 To update Identity Server to establish the trust relationship with Access Gateway, click Devices > 
Identity Servers > Update > OK. 


Wait until the Command status is Complete and the Health status is green. 


10 (Optional). To test this configuration from a client browser, specify the published DNS name as 
the URL in the browser. In the example illustrated in Figure 3-2 on page 58, specify the following 
URL: 


http://www.mytest.com 


This must resolve to the published DNS name you specified in Step 8 on page 106, and the user 
must be connected to the web server through Access Gateway. 


11 Continue with Section 3.6.3, “Configuring Access Gateway for Authentication,” on page 108. 


IMPORTANT: You must not modify the default NAM-Service proxy service. 


Configuring Access Gateway for Authentication 


The procedures in Section 3.6.1, “Configuring a Reverse Proxy,” on page 105 and Section 3.6.2, 
“Configuring a Public Protected Resource,” on page 107set up Access Gateway to protect your web 
server by hiding its IP address and DNS name from Internet users. The procedure does not require 
the user to log in before accessing resources on the web server. This section explains how to 
configure Access Gateway so that the users are required to provide login credentials before they 
access to a protected resource. This configuration consists of two parts: 


¢ Section 3.6.3.1, “Verifying Time Synchronization,” on page 108 
¢ Section 3.6.3.2, “Enabling Trusted Authentication,” on page 109 


Verifying Time Synchronization 


The time must be synchronized between Identity Server and Access Gateway or set so the time 
difference is within one minute of each other for trusted authentication to work. 


For Identity Server or Linux Access Gateway Service, use YaST to verify the time settings. For a 
Windows Access Gateway Service, use the Date and Time option in the Control Panel. If you have a 
Network Time Protocol server, configure the Access Manager machines to use it. 
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For an Access Gateway Appliance, complete the following steps: 


1 Click Devices > Access Gateways> Edit > Date & Time. 
2 Select a method you want to use for time: 


Set Date & Time Manually: Allows you to select the current time. Click this option to select 
year, month, day, hour, and minute in your current time zone, then click OK. 


Set Up NTP: Allows you to specify the IP address of an NTP server. Click Set Up NTP. Use the 
public pool.ntp.org server or click New, then specify the IP address of an NTP server. To accept 
the configuration, click OK. 


If the time on the machine is wrong by more than an hour, use both methods to set the time. Set 
it manually first, and then configure it to use NTP. 


3 In the Time Zone section, select your time zone, then click OK. 

Regardless of the method you used to set the time, you must select a time zone. 
4 Click OK. 
5 Click Devices > Access Gateways > Update > OK. 


Continue with “Enabling Trusted Authentication” on page 109. 


Enabling Trusted Authentication 


Trusted authentication requires an authentication contract that specifies the type of authentication 
credentials. Identity Server and Access Gateway control these authentication requirements. You do 
not need to configure your web server to require authentication. Access Manager enforces the 
requirements for you. 


In this example, you set up an authentication contract that requires a username and a password to 
access a directory on a web server. 


1 Click Devices > Access Gateways, then click Edit > [Name of Reverse Proxy] > [Name of Proxy 
Service] > Protected Resources > New. 

2 Specify a display name for the protected resource, then click OK. 

3 Select one of the following in Authentication Procedure: 


Name/Password - Basic: Basic authentication over HTTP using a standard login page provided 
by the web browser. 


Name/Password - Form: Form-based authentication over HTTP. 


Others are available, but for this basic setup, which does not enable SSL, select one of the 
above contracts. The contract needs to match the protocol. 


If these default authentication contracts are not available, you have not configured a relationship 
between Access Gateway and Identity Server. See Section 3.6.1, “Configuring a Reverse 
Proxy,” on page 105 and select a value for the Identity Server Cluster field. 


4 In URL Path List, configure the URL path to the page that this authentication contract will protect. 
For the web server configuration described in “Prerequisites for Setup” on page 58, click the /* 
path and modify it to specify the following path: 


/protected/* 


5 Click OK > OK. 
6 Click Devices > Access Gateways > Update > OK. 
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7 


8 


(Optional) To test this configuration from a client browser, log in to Access Gateway: 
7a Specify the published DNS name to this resource in the browser. For the example illustrated 
in Figure 3-2 on page 58, you would specify the following URL: 
http://www.mytest.com 
7b Click the link to the protected page. This must be a link to the same page you configured in 
Step 4. 


Your browser must prompt you with a login page. If you selected Name/Password - Basic as 
the contract, the standard login page issued by your browser is displayed. If you selected 
Name/Password - Form, the default Access Manager login page is displayed. 


7c Log in to Identity Server with a username and password that is stored in your LDAP 
directory (Server 3 in Figure 3-2 on page 58). 


You must have access to the information you have placed in the protected directory on 
your web server. 


If you have set up your web server to require basic authentication to access this directory, 
you are prompted again for login credentials. 


If you receive an error, see “Common Authentication Problems” on page 235. 
Continue with “Setting Up Policies” on page 110. 


Setting Up Policies 


Access Gateway lets you retrieve information from your LDAP directory and inject the information into 
HTML headers, query strings, or basic authentication headers. Access Gateway can then send this 
information to the back-end web servers. Access Manager calls this technology Identity Injection. 


This is one of the features within Access Manager that enables single sign-on. Users are prompted 
for the login credentials for one time, and Access Manager then supplies them for the resources you 
have configured for Identity Injection. 


This section explains how to set up an Identity Injection policy for basic authentication. This policy is 
assigned to the third directory on your web server, which is the basic directory that your web server 
has been configured to require basic authentication before allowing access. 


1 


Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service Name] > 
Protected Resources > New. 


Configure the resource for the basic directory as described in Section 3.2, “Prerequisites for 
Setup,” on page 58: 


2a For the contract, select Name/Password - Basic or Name/Password - Form. 
2b For the URL path, specify the path to the basic directory (/basic/*). 

2c Click OK. 

Click [Protected Resource Name] > Identity Injection. 


On a new installation, the list is empty because no policies have been created. 


4 In the Identity Injection Policy List section, click Manage Policies. 


In the Policy List section, click New, then specify values for the following fields: 
Name: Specify a name for the Identity Injection policy. 

Type: Select Access Gateway: Identity Injection. 

Click OK. 

(Optional) Specify a description for the policy. 
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3.7 


8 In the Actions section, click New > Inject into Authentication Header. 
9 Set up the policy for User Name and Password: 
+ For User Name, select Credential Profile and LDAP Credentials: LDAP User Name. 
This injects the value of the cn attribute into the header. 
+ For Password, select Credential Profile and LDAP Credentials: LDAP Password. 
The policy must look similar to the following: 


Type: Access Gateway: Identity Injection 
Description: Authentication header policy 
Priority: 1 

Actions 


New w 


Do Inject into Authentication Header 
User Name: Credential Profile w : LDAP User Name w 
Password: Credential Profile w : LDAP Password w 


Multi-Value Separator; ,¥ 


DN Format: LDAP (ex, cn=jsmith,ou=Sales,o=Novell) v 


changes made on this panel must be applied from the Policies Panel. 


OK Cancel | 


10 Click OK > OK > Apply Changes > Close. 
11 Select the new Identity Injection policy, then click Enable > OK. 
12 Click Devices > Access Gateways > Update > OK. 


13 To test this configuration from a client browser, specify the published DNS name as the URL in 
the browser. Click the link to the page that uses basic authentication. 


You are prompted to log in. If you have set up web applications on your web server that require 
login, any additional login prompts are hidden from the user and are handled by the identity 
injection system. 


For an example of how Identity Injection policies can be used for single sign-on to the Identity 
Manager User Application, see “Configuring Access Manager for UserApp and SAML” (http:// 
www.novell.com/coolsolutions/appnote/19981.html). 


Access Gateways Clusters 


A cluster of Access Gateways must reside behind a Layer 4 (L4) switch. Clients access the virtual IP 
on the L4, and the L4 alleviates server load by balancing traffic across the cluster of Access 
Gateways. Whenever a user enters the URL for an Access Gateway resource, the request is routed 
to the L4 switch, and the switch routes the user to one of Access Gateways in the cluster, as traffic 
necessitates. 


Figure 3-4 illustrates the flow of a user request when Access Gateways are clustered behind an L4 
switch. 
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3.7.1 


Figure 3-4 Clustering Access Gateways 
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1. The user requests access to a protected resource by sending a request to the L4 switch. The 
request is sent to one of Access Gateway servers in the cluster. 


2. Access Gateway redirects the request to Identity Server for authentication. Identity Server 
presents the user with a login page, requesting a user name and a password. 


3. Identity Server verifies the user’s credentials with the directory. 


4. The validated credentials are sent through the L4 switch to the same Access Gateway that first 
received the request. 


5. Access Gateway verifies the user credentials with Identity Server. 
6. If the credentials are valid, Access Gateway forwards the request to the web server. 


If Access Gateway where the user's session was established goes down, the user’s request is sent to 
another Access Gateway in the cluster. This Access Gateway pulls the user’s session information 
from Identity Server. This allows the user to continue accessing resources, without having to re- 
authenticate. 


IMPORTANT: You must not use a DNS round robin setup instead of an L4 switch for load balancing. 
The DNS solution works only as long as all members of the cluster are working and in a good state. If 
one of them goes down and traffic is still sent to that member, the entire cluster is compromised and 
starts generating errors. 


The following sections describe how to set up and manage a cluster of Access Gateways. 
¢ Section 3.7.1, “Prerequisites,” on page 112 
¢ Section 3.7.2, “Designing the Membership Type for a Cluster,” on page 113 
¢ Section 3.7.3, “Configuring a Cluster,” on page 113 
¢ Section 3.7.4, “Managing Access Gateway Cluster Configuration,” on page 114 


Prerequisites 


©) AnL4 switch is installed. You can use the same switch for an Identity Server cluster and an 
Access Gateway cluster, provided that you use different virtual IPs. 


O One or more Access Gateways is installed. 


When you install a new Access Gateway, configure it to use the same Administration Console. 
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3.7.2 


3.7.3 


O Your DNS server must to be configured to resolve the published DNS names that you specify for 
your proxy services to the L4 switch. 


O Persistent (sticky) sessions on the L4 switch is enabled (highly recommended, but not 
mandatory). 


IMPORTANT: If you have created a configuration for one or more of Access Gateways you are going 
to put in a cluster, you need to carefully select the primary cluster server. The current configuration of 
the primary cluster server is pushed to the other servers in the cluster. If you have created 
configurations for the other servers in the cluster, these configurations are overwritten. 


Designing the Membership Type for a Cluster 


You can create a cluster of all Gateway Appliances or of all Gateway Services. The Gateway 
Services cluster can be either all in Linux or all in Windows. 


When you create a cluster of Access Gateways that are of the same type, you can guarantee that the 
user experience is always the same, regardless of which Access Gateway the user establishes a 
connection to. For a list of the differences between Access Gateway Appliance and Access Gateway 
Service, see Feature Comparison of Different Types of Access Gateways in the NetIQ Access 
Manager 4.3 Installation and Upgrade Guide. 


Configuring a Cluster 


1 Click Devices > Access Gateways > New Cluster. 

2 Specify the following details: 
Cluster Name: Specify a display name for the cluster. 
Type: Select the type of cluster you want to create: Gateway Appliance or Gateway Service. 
Primary Cluster Server: Select the server that is to be the primary server in the cluster. 

3 In the Server Name list, select the servers that you want to be members of the cluster. 


You can create a cluster of one, and add additional servers later. You cannot create a cluster that 
contains Access Gateway Appliances and Access Gateway Services. The cluster can contain 
only one type of Access Gateway. 


Each server you add to the cluster adds about 30 seconds to the time it takes to configure the 
cluster because certificates must be synchronized and configuration options must be sent to that 
server. If you create a very large cluster of twenty servers, it can take up to ten minutes to 
configure and create the cluster. 


4 Click OK. 


5 After the cluster has been created, each server in the cluster needs be restarted. On the Access 
Gateways page, click Update All by the name of the cluster. 


6 (Conditional) If Access Gateways in the cluster have multiple network adapters or IP addresses, 
you need to configure the listening address for each reverse proxy. 


When you create the cluster configuration for newly added servers, the listening address is 
always the IP address of ethO. If this is not the address where you want the reverse proxy to 
listen for requests, click Access Gateways > Edit > [Name of Reverse Proxy], select Access 
Gateway as the Cluster Member, then enable the Listening Address you want to use. 


7 To configure the cluster, click Access Gateways > Edit. 
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A cluster of Access Gateways has the same configuration options as a single Access Gateway. 
The only difference is that for some options you need to select Access Gateway to configure. For 
example, the Date & Time option allows you to set the time separately for each member of the 
cluster. 


Applying the configuration to a cluster is slightly different. You have the option to apply the 
changes to all servers in the cluster by selecting the Update All option, or to apply them to one 
server at a time by selecting the Update option for each server. When you update the servers 
one at time, your site remains up. For more information on the Update and Update All options, 
see “Configuration Options” on page 307. 


If you prefer to apply changes to the servers one at time, you must save the changes to the 
configuration datastore on the Server Configuration page. (The OK buttons on the other 
configuration pages save the changes to browser cache.) If your session times out before you 
update all servers in the cluster and the changes have been saved only in browser cache, the 
changes are lost and are not applied to the servers that are still in an Update status. 


3.7.4 Managing Access Gateway Cluster Configuration 


This section describes the tasks that are specific to managing the servers in a cluster: 


+ 


+ 


+ 


+ 


+ 


+ 


Section 3.7.4.1, “Creating a New Cluster,” on page 114 

Section 3.7.4.2, “Managing Access Gateway Servers in the Cluster,” on page 115 
Section 3.7.4.3, “Managing Cluster Details,” on page 115 

Section 3.7.4.4, “Editing Cluster Details,” on page 116 

Section 3.7.4.5, “Changing the Primary Cluster Server,” on page 116 

Section 3.7.4.6, “Applying Changes to Access Gateway Cluster Members,” on page 116 


Creating a New Cluster 


Click Devices > Access Gateways > New Cluster. 


2 Specify the following details: 


Cluster Name: Specify a display name for the cluster. 
Type: Select the type of cluster you want to create: Gateway Appliance or Gateway Service. 


Primary Cluster Server: Select the server that is to be the primary server in the cluster. This 
field is empty until you have selected one or more servers to be members of the cluster. 


In the Server Name list, select the servers that you want to be members of the cluster. 


You can create a cluster of one and add additional servers later.You cannot create a cluster that 
contains Access Gateway Appliances and Access Gateway Services. The cluster can contain 
only one type of Access Gateway. 


Each server you add to the cluster adds about 30 seconds to the time it takes to configure the 
cluster because certificates must be synchronized and configuration options must be sent to that 
server. If you create a very large cluster of twenty servers, it can take up to ten minutes to 
configure and create the cluster. 


4 Select the server you want to be the Primary Cluster Server. 


3.7.4.1 
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Click OK. 
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6 After the cluster has been created, each server in the cluster needs be restarted. On the Access 
Gateways page, click Update All by the name of the cluster. 


For information on additional required configuration tasks, see Section 3.7.4, “Managing Access 
Gateway Cluster Configuration,” on page 114. 


3.7.4.2 Managing Access Gateway Servers in the Cluster 


To view the servers that are currently members of clusters: 


1 Click Devices > Access Gateways. 


The members of a cluster are listed under the cluster name. The red double dagger symbol 
identifies the server that is the primary cluster server. 


2 To add a server to a cluster, select the server, then click Actions > Assign to Cluster > [Name of 
Cluster]. 


A cluster cannot contain both Access Gateway Appliances and Access Gateway Services. The 
cluster can contain only one type of Access Gateway. 


3 To remove a server from a cluster, select the server, then click Actions > Remove from Cluster. 


Usually when you delete a server from a cluster, you have discovered that traffic is lighter than 
anticipated and that it can be handled with fewer machines while another cluster is experiencing 
higher traffic and can benefit from having another cluster member. When the server is removed, 
its configuration object maintains all the configuration settings from the cluster. When it is added 
to a new cluster, its configuration object is updated with the configuration settings of the new 
cluster. If your clusters are behind an L4 switch, you need to reconfigure the switch so that the 
server is assigned to the correct cluster. 


When a server is removed from a cluster, its Embedded Service Provider is stopped. If you are 
not going to assign it to another cluster, you need to reconfigure the server so that it is protecting 
resources other than the ones it protected in the cluster. When you apply the changes by clicking 
Update, the Embedded Service Provider is restarted. 


You cannot remove the primary cluster server unless it is the only server in the cluster. If you 
need to remove the primary cluster server from a multiple server cluster, you need to assign 
another the server to be the primary cluster server. 


4 To modify which server is the primary cluster server, see “Changing the Primary Cluster Server” 
on page 116. 


5 To view detailed information about a server in the group, click the name of the server. 
6 To view detailed health information about a server, click the health icon of the server. 
7 Click Close. 


3.7.4.3 Managing Cluster Details 


Use the Cluster Details page to perform general maintenance actions on the selected cluster and to 
display server information about the selected cluster. 
1 Click Devices > Access Gateways > [Cluster Name]. 
2 View the following fields: 
Name: Specifies the name of the cluster. 


Description: Specifies the purpose of the cluster. This is optional, but useful if your network has 
multiple Access Gateway clusters. If the field is empty, click Edit to add a description. 


Primary Server: Indicates which server in the cluster has been assigned to be the primary 
server. 
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3.7.4.4 


3.7.4.5 


3.7.4.6 


3 To modify the information, click Edit. For more information, see “Editing Cluster Details” on 
page 116. 


4 To select a different Access Gateway to be the primary cluster member, click Edit. 
5 To modify details about a cluster member, click the server name in the Cluster member list. 
6 Click Close. 


Editing Cluster Details 


Use the Cluster Detail Edit to change the name of the cluster and assign a different server to be the 
primary cluster member. 
1 Click Devices > Access Gateways > [Cluster Name] > Edit. 
2 Modify the following fields: 
Name: Specify a name for the cluster. 


Description: Specify the purpose of the cluster. This is optional, but useful if your network has 
multiple Access Gateway clusters. 


Primary Server: Indicates which server in the cluster has been assigned to be the primary 
server. To change this assignment, select the server from the drop-down list. For more 
information on this process, see “Changing the Primary Cluster Server” on page 116. 


3 Click OK. 


Changing the Primary Cluster Server 


If the current primary cluster server is down and will be down for an extended period of time, you must 
select another server to be the primary cluster server 


1 Click Devices > Access Gateways > [Name of Cluster] > Edit. 
2 Inthe Primary Server list, select the name of a server, then click OK. 


Wait until this configuration change has completed, before doing any other configuration 
updates. 


3 To update Identity Server, click Identity Servers > Update. 


Applying Changes to Access Gateway Cluster Members 


When you are configuring services of Access Gateway, the OK button saves the change to browser 
cache except on the Configuration page. The Configuration page (Devices > Access Gateways > 
Edit) provides a summary of the changes you have made. The Cancel Change column allows you to 
cancel changes to individual services. When you click OK, the changes are saved to the configuration 
datastore, and you no longer have the option to cancel changes to individual services. 


If you don’t save the changes to the configuration datastore and your session times out or you log out, 
any configuration changes that are saved to browser cache are flushed. These changes cannot be 
applied to other members of the cluster because they are no longer available. To prevent this from 
happening, save the changes to the configuration datastore. 
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It is especially important to save the changes to the configuration datastore when you select to 
update individual members one at a time rather than update all members of the cluster at the same 
time. Updating members one at a time has the following benefits: 


+ When you update all servers at the same time, the site goes down until one server has finished 
updating its configuration. If you update the cluster members one at a time, only the member that 
is updating its configuration becomes unavailable. 


+ If you update the servers one at time, you can verify that the changes are behaving as expected. 
After testing the configuration on one server, you can then apply the saved changes to the other 
servers in the cluster. If you decide that the configuration changes are not behaving as expected, 
you can revert to the previously applied configuration. See “Reverting to a Previous 
Configuration” on page 117. 


Some configuration changes cannot be applied to individual cluster members. For a list of these 
changes, see “Modifications Requiring an Update All” on page 117. 


Reverting to a Previous Configuration 


If you have updated only one server in the cluster, you can use the following procedure to revert back 
to the previous configuration. 
1 Remove the server that you have applied the configuration changes from the cluster. 
2 Access the Configuration page for the cluster, then click Revert. 
The servers in the cluster revert to the last applied configuration. 
3 Add the removed server to the cluster. 
The server is configured to use the same configuration as the other cluster members. 


Modifications Requiring an Update All 


When you make the following configuration changes, the Update All option is the only option 
available and your site is unavailable while the update occurs: 


¢ If you change Identity Server configuration that is used for authentication (Access Gateways > 
Edit > Reverse Proxy/Authentication, then select a different value for the Identity Server Cluster 
option). 

¢ If you select a different reverse proxy to use for authentication (Access Gateways > Edit > 
Reverse Proxy/Authentication, then select a different value for the Reverse Proxy option). 


¢ If you modify the protocol or port of the authenticating reverse proxy (Access Gateways > Edit > 
Reverse Proxy/Authentication > [Name of Reverse Proxy], then change the SSL options or the 
port options). 


+ If you modify the published DNS name of the authentication proxy service (Access Gateways > 
Edit > Reverse Proxy/Authentication > [Name of Reverse Proxy] > [Name of First Proxy 
Service], then modify the Published DNS Name option). 
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3.8 


3.8.1 


Protecting Web Resources Through Access 
Gateway 


Access Gateway is a reverse proxy server (protected site server) that restricts access to web-based 
content, portals, and web applications that employ authentication and access control policies. It also 
provides single sign-on to multiple web servers and web applications by securely providing the 
credential information of authenticated users to the protected servers and applications. Access 
Gateway lets you simplify, secure, and accelerate your Internet business initiatives. 


This section describes the following tasks: 


¢ Section 3.8.1, “Configuration Options,” on page 118 

¢ Section 3.8.2, “Managing Reverse Proxies and Authentication,” on page 119 
¢ Section 3.8.3, “Configuring Web Servers of a Proxy Service,” on page 126 

¢ Section 3.8.4, “Configuring Protected Resources,” on page 128 

¢ Section 3.8.5, “Configuring HTML Rewriting,” on page 139 

¢ Section 3.8.6, “Configuring Connection and Session Limits,” on page 156 

¢ Section 3.8.7, “Protecting Multiple Resources,” on page 161 


Configuration Options 


A typical Access Manager configuration includes an Identity Server with LDAP directories and an 
Access Gateway with a protected web server. Figure 3-5 illustrates the process flow that allows an 
authorized user to access the protected resource on the web server. 


Figure 3-5 Accessing a Web Resource 
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1. The user requests access to a resource protected by Access Gateway. 


2. Access Gateway redirects the user to Identity Server, which prompts the user for a username 
and password. 


3. Identity Server verifies the username and password against an LDAP directory (eDirectory, 
Active Directory, or Sun ONE). 


4. Identity Server returns an authentication success to the browser and the browser forwards the 
resource request to Access Gateway. 


5. Access Gateway verifies that the user is authenticated and retrieves the user’s credentials from 
Identity Server. 
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6. Access Gateway uses an Identity Injection policy to insert the basic authentication credentials in 
the HTTP header of the request and sends it to the web server. 


7. The web server grants access and sends the requested page to the user. 


When you are setting up Access Gateway to protect web resources, you create and configure 
reverse proxies, proxy services, and protected resources. The following figure illustrates the 
hierarchy of these modules and the major configuration tasks you perform on each module. 


Figure 3-6 Access Gateway Modules and Their Configuration Options 
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This hierarchy allows you to have precise control over what is required to access a particular 
resource, and also allows you to provide a single sign-on solution for all the resources protected by 
Access Gateway. The authentication contract, authentication procedure, Authorization policy, Identity 
Injection policy, and Form Fill policy are configured at the resource level so that you can enable 
exactly what the resource requires. This allows you to decide where access decisions are made: 


¢ You can configure Access Gateway to control access to the resource. 


¢ You can configure the web server for access control and configure Access Gateway to supply 
the required information. 


+ You can use the first method for some resources and the second method for other resources or 
use both methods on the same resource. 


Managing Reverse Proxies and Authentication 


A reverse proxy acts as the front end to your web servers on your Internet or intranet and off-loads 
frequent requests, thereby freeing up bandwidth. The proxy also increases security because the IP 
addresses of your web servers are hidden from the Internet. 


To create a reverse proxy, you must create at least one proxy service with a protected resource. You 
must supply a name for each of these components. Reverse proxy names and proxy service names 
must be unique to Access Gateway because they are configured for global services such as IP 
addresses and TCP ports. For example, if you have a reverse proxy named products and another 
reverse proxy named library, only one of these reverse proxies can have a proxy service named 
corporate. 


Protected resource names need to be unique to the proxy service, but they don’t need to be unique to 
Access Gateway because they are always accessed through their proxy service. For example, if you 
have a proxy service named account and a proxy service named sales, they both can have a 
protected resource named public. 
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The first reverse proxy and proxy service you create are automatically assigned to be the 
authenticating proxy. 


1 Click Devices > Access Gateways > Edit. 


The Edit link is either for a single Access Gateway or for a cluster of Access Gateways. 


2 Click Reverse Proxy / Authentication. 


3 Configure the authentication settings: 


Identity Server Cluster: Specifies Identity Server you want Access Gateway to trust for 
authentication. Select the configuration you have assigned to Identity Server. 


Whenever an Identity Server is assigned to a new trust relationship, Identity Server needs to be 
updated. This process is explained following the step that saves this configuration setting (see 
Step 5 on page 123 and Step 6 on page 123). 


(Conditional) If you have already created at least one reverse proxy, you can view the Embedded 
Service Provider options and configure some of them: 


Reverse Proxy: Specifies which proxy service is used for authentication. If you have configured 
only one proxy service, only one appears in the list and it is selected. If you change the reverse 
proxy that is used for authentication, certificates must be updated to match this new 
configuration. 


Metadata URL: Displays the location of the metadata. 
Health-Check URL: Displays the location of the health check. 


Logout URL: Displays the URL that you need to use for logging users out of protected 
resources. This value is empty until you have created at least one reverse proxy and it has been 
assigned to be used for authentication. If you create two or more reverse proxies, you can select 
which one is used for authentication, and the logout URL changes to match the assigned reverse 
proxy. 


If any of your protected resources have a logout page or button, you need to redirect the user’s 
logout request to the page specified by this URL. Access Gateway can then clear the user’s 
session and log the user out of any other resources that have been enabled for single sign-on. If 
you do not redirect the user’s logout request, the user is logged out of one resource, but the 
user’s session remains active until inactivity closes the session. If the user accesses the 
resource again before the session is closed, single sign-on reauthenticates the user to the 
resource, and it appears that the logout did nothing. 


ESP Global Options: Allows you to configure global options for ESP. For more information, see 
“Configuring ESP Global Options” on page 124. 


Auto-Import Identity Server Configuration Trusted Root: Allows you to import the public key 
from Identity Server cluster into the trust store of the Embedded Service Provider. This sets up a 
trusted SSL relationship between the Embedded Service Provider and Identity Server. This 
option is not available until you have selected an Identity Server Cluster and have configured 
the use of SSL on the Embedded Service Provider of the reverse proxy that is performing 
authentication (see the Enable SSL with Embedded Service Provider option on the Reverse 
Proxy page). 


If Identity Server cluster is using a certificate created by the Access Manager certificate authority 
(CA), the public key is automatically added to this trust store, so you do not need to use this 
option. If Identity Server cluster is using a certificate created by an external CA, you need to use 
this option to import the public key into the trust store. 


5 (Optional) Configure the proxy settings: 
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Behind Third Party SSL Terminator: Enable this option if you have installed an SSL terminator 
between the users and Access Gateway. This allows the terminator to handle the SSL traffic 
between the browsers and the terminator. The terminator and Access Gateway can use HTTP 
for their communication. For configuration tips, see “Using an SSL Terminator” on page 985. 


Enable Via Header: Enables the sending of the Via header to the web server. The Via header 
contains the DNS name of Access Gateway and a device ID. It has the following format: 
Via: 1.1 www.mymag.com (Access Gateway-ag-BFBA9849520DB63B-5) 
Deselect this option when your web server does not need this information or does not know what 
to do with it. 

6 (Optional) Configure the cookie settings: 


For more information and other options for securing Access Manager cookies, see Section 10.6, 
“Enabling Secure Cookies,” on page 928. 


Enable Secure Cookies: Enabling this option sets secure keyword on HTTPS request. If you 
have enabled the Behind Third Party SSL Terminator option and also enabled the Enable 
Secure Cookies option, the secure keyword on HTTP and HTTPS requests are set. 


WARNING: Do not enable the Enable Secure Cookies option if you have both HTTP and 
HTTPS reverse proxies. The HTTP services become unavailable because authentication 
requests to the non-HTTP services fail. 


Force HTTP-Only Cookie: Forces Access Gateway to set the HttpOnly keyword, which prevent 
scripts from accessing the cookie. This helps protect browsers from cross-site scripting 
vulnerabilities that allow malicious sites to grab cookies from a vulnerable site. The goal of such 
attacks might be to perform session fixation or to impersonate the valid user. 


IMPORTANT: The HttpOnly keyword can prevent applets from loading and can interfere with 
JavaScript. Do not enable this option if you have Access Gateway protecting applications that 
download applets or use JavaScript. 


7 To create a proxy service, continue with “Creating a Proxy Service” on page 121. 


3.8.2.1 Creating a Proxy Service 


1 Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication. 
2 In the Reverse Proxy List, click New, specify a display name for the reverse proxy, then click OK. 
3 Enable a listening address. Fill in the following fields: 


Cluster Member: (Available only if Access Gateway is a member of a cluster.) Select the server 
you want to configure from the list of servers. The Listening Address(es) and TCP Listen 
Options modifications apply to the selected server. Modifications made to any other options on 
the page apply to all servers in the cluster. 


Listening Address(es): Displays a list of available IP addresses. If the server has only one IP 
address, only one is displayed and it is automatically selected. If the server has multiple 
addresses, you can select one or more IP addresses to enable. You must enable at least one 
address by selecting its check box. 


If Access Gateway is in a cluster, you must select a listening address for each cluster member. 


TCP Listen Options: Provides options for configuring how requests are handled between the 
reverse proxy and the client browsers. You cannot set up the listening options until you create 
and configure a proxy service. For information about these options, see “Configuring TCP Listen 
Options for Clients” on page 157. 
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4 Configure the listening ports: 


Non-Secure Port: Specifies the port on which to listen for HTTP requests; the default port for 
HTTP is 80. Depending upon your configuration, this port might also handle other tasks. These 
tasks are listed to the right of the text box. 


Secure Port: Specifies the port on which to listen for HTTPS requests; the default port for 
HTTPS is 443. 


For information about the SSL options, see “Configuring Access Gateway for SSL” on page 980. 
5 In the Proxy Service List section, click New. 


The first proxy service of a reverse proxy is considered the master (or parent) proxy. Subsequent 
proxy services can use domain-based, path-based, or virtual multi-homing, relative to the 
published DNS name of the master proxy service. If you are creating a second proxy service for 
a reverse proxy, see “Using Multi-Homing to Access Multiple Resources” on page 161. 


6 Fill in the fields: 


Proxy Service Name: Specify a display name for the proxy service, which Administration 
Console uses for its interfaces. 


Published DNS Name: Specify the DNS name you want the public to use to access your site. 
This DNS name must resolve to the IP address you set up as the listening address. 


Web Server IP Address: Specify the IP address of the web server you want this proxy service 
to manage. You can specify additional web server IP addresses by clicking the Web Server 
Addresses link when you have finished creating the proxy service. 


Host Header: Specify whether the HTTP header must contain the name of the back-end web 
server (Web Server Host Name option) or whether the HTTP header must contain the published 
DNS name (the Forward Received Host Name option). 


Web Server Host Name: Specify the DNS name of the web server that Access Gateway must 
forward to the web server. If you have set up a DNS name for the web server and it requires its 
DNS name in the HTTP header, specify that name in this field. If the web server has absolute 
links referencing its DNS name, include this name in this field. If you selected Forward Received 
Host Name, this option is not available. 


NOTE: For iChain administrators, the Web Server Host Name is the alternate hostname when 
configuring a Web Server Accelerator. 


7 Click OK. 
8 Continue with “Configuring a Proxy Service” on page 122 or select one of the following tasks: 


¢ For information about how to create multiple reverse proxies, see “Managing Multiple 
Reverse Proxies” on page 172. 


¢ For information about how to create multiple proxy services for a reverse proxy, see “Using 
Multi-Homing to Access Multiple Resources” on page 161. 


3.8.2.2 Configuring a Proxy Service 
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A reverse proxy can have multiple proxy services, and each proxy service can protect multiple 
resources. You can modify the following features of the proxy service: 


+ Web servers 
¢ HTML rewriting 


e Logging 
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+ Protected resources 
+ Caching 


1 Toconfigure a proxy service, click Access Gateways > Edit > [Name of Reverse Proxy] > [Name 
of Proxy Service]. 


2 Fill in the following fields: 


Published DNS Name: Displays the value that users are currently using to access this proxy 
service. This DNS name must resolve to the IP address you set up as a listening address on 
Access Gateway. You must modify this field only if you have modified the DNS name you want 
users to use to access this resource. 


This name determines the possible values of the Cookie Domain. 


Description: (Optional). Provides a field where you can describe the purpose of this proxy 
service or specify any other pertinent information. 


Cookie Domain: Specifies the domain for which the cookie is valid. 


If one proxy service has a DNS name of www.support.novell.com and the second proxy service 
has a DNS name of www.developernet.novell.com, the cookie domains are support.novell.com 
for the first proxy service and developernet.novell.com for the second proxy service. You can 
configure them to share the same cookie domain by selecting novell.com for each proxy service. 
Single sign-on between the proxy services is simplified when the proxy services share the same 
cookie domain. 


HTTP Options: Allows you to set up custom caching options for this proxy service. See 
Section 4.3.2, “Controlling Browser Caching,” on page 333. 


Advanced Options: Access Gateway Service) Specifies how the proxy service handles specific 
conditions, such as web server error pages. If similar options are configured globally, the proxy 
service configuration overwrites the global setting. For configuration information on the proxy 
service options, see Section 4.4.2, “Configuring Advanced Options for Domain-Based and Path- 
Based Multi-Homing Proxy Services,” on page 346. 


3 Click OK to save your changes to browser cache. 
4 Click Devices > Access Gateways. 
5 To apply your changes, click Update > OK. 


Until this step, nothing has been permanently saved or applied. The Update status pushes the 
configuration to the server and writes the configuration to the configuration data store. When the 
update has completed successfully, the server returns the status of Current. 


To save the changes to the configuration store without applying them, do not click Update. 
Instead, click Edit. On the Configuration page, click OK. The OK button on this pages saves the 
cached changes to the configuration store. The changes are not applied until you click Update 
on Access Gateways page. 


6 Update Identity Server to accept the new trusted relationship. Click Identity Servers > Update. 
7 Continue with one of the following. 


+ Ifthe web server that contains the resources you want to protect does not use the standard 
HTML port (port 80), you need to configure the web server. See Section 3.8.3, “Configuring 
Web Servers of a Proxy Service,” on page 126. 


¢ Until you configure a protected resource, the proxy service blocks access to all services on 
the web server. To configure a protected resource, see Section 3.8.4, “Configuring 
Protected Resources,” on page 128. 
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3.8.2.3 


3.8.2.4 


Modifying the DNS Setting for a Proxy Service 


1 


Get the SSL certificate for the new DNS name. 
For more information, see Chapter 13, “Creating Certificates,” on page 947. 


2 Click Devices > Access Gateways. 


3 Edit AG-Cluster and click on any reverse proxy listed under Reverse Proxy/Authentication. 


4 Change the Server Certificate to the new one for your new DNS name. 


Ignore any warning displayed about CN name mismatch because the proxy service is not yet 
updated. 


5 Under the Proxy Service List tab, click the proxy which DNS name you want to modify. 


6 Change the Published DNS Name for the proxy service. 


NOTE: Changing the published DNS name of the master proxy changes Identity Server’s base 
URL also. 


7 Click OK > OK. 
8 The Cluster Configuration page is displayed. 


9 Click Network Settings > Hosts > IP address of your system. 


Add the new DNS name in the list of host names. 
Click OK. 

Go to Access Gateway. 

Click Update All. 


When Access Gateway Health turns green, check Identity Server Health and ensure that it is 
green as well. 


Configuring ESP Global Options 


When you configure an ESP global option, it gets applied to all Access Gateway ESPs in an Access 
Gateway cluster. 


By default, these options are disabled. To enable these options, you need to remove the pound (#) 
symbol before it and set a value. After you configure an option, you cannot delete it. However, you 
can disable it again by adding the pound (#) symbol before it. If you have set a value for an option and 
want to disable the option, you need to add # before the configured option. After saving the changes, 
the value for the option is set to the default value. For example, if you have set the value for 
CLUSTER_COOKIE_DOMAIN as CLUSTER_COOKIE_DOMAIN .example.com, add # before 
CLUSTER_COOKIE_ DOMAIN .example.com. After the changes are applied, the option is set to the 
default value as #CLUSTER_COOKIE_DOMAIN. 


NOTE: Access Manager 4.2 onwards, configuring the following options through files is deprecated. 
You must configure these option by using Administration Console. 


Perform the following steps to configure ESP global options: 


1 


2 


Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication > ESP Global 
Options. 


To activate an ESP global option, remove the # symbol before it, configure the value, save it, and 
then update Access Gateway. By default, Access Manager displays seven options. You can 
configure any other options also, if required. 


124 Setting Up a Basic Access Manager Configuration 


The following table lists the default ESP global options: 


ESP Global Option 


forceESPSLOHTTP 


httponlyClusterCookie 


CLUSTER_COOKIE_DOMAIN 


CLUSTER_COOKIE_PATH 


notifysessionTimetolIDP 


RENAME_SESSIONID 


IS_DISPLAY_AUTH_DONE_PAGE 


SESSION_ASSURANCE_USER 
AGENT_EXCLUDE_LIST 
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Description 


Set true to enable the front channel logout for Access 
Gateway initiated logout. 


The default value is false. 


For more information about how to enable front 
channel logout for Access Gateway, see “Defining 
Options for Liberty Identity Provider’ on page 515. 


Set false to disable the HTTPOnly flags for ESP 
cluster cookies. 


The default value is true. 


For example, see Section 30.3.11, “Enabling Secure 
or HTTPOnly Flags for Cluster Cookies,” on 
page 1208. 


Set this property to change the Domain attribute for 
the ESP custer cookie in this format: 
CLUSTER_COOKIE_DOMAIN .example.com 


Set this property to change the Path attribute for the 
ESP custer cookie. 


The default value is /nesp. 


Set false to disable sending session timeout message 
to the remote identity provider. 


The default value is true. 


For example, see “Configuring the Liberty or SAML 2.0 
Session Timeout” on page 492. 


Set false to prevent changing Access Gateway 
session ID automatically. 


The default value is true. 


For example, see “Preventing Automatically Changing 
Session ID” in the “Securing the Embedded Service 
Provider Session Cookie on Access Gateway” on 
page 928. 


Set true to enable Access Gateway to display post- 
authentication message. 


The default value is false. 


For example, see Section 4.2.8, “Enabling Access 
Gateway to Display Post-Authentication Message,” on 
page 324. 


Specify the user-agent string for that you want to 
disable the session validation. 


For example, see “Disabling Advanced Session 
Assurance for Access Gateway ESP” on page 938. 
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ESP Global Option 


SESSION_ASSURANCE_USER_AGENT_REGEX_E 
XCLUDE_LIST 


SESSION_ASSURANCE_URL_EXCLUDE_LIST 


SESSION_ASSURANCE_URL_REGEX_EXCLUDE_ 
LIST 


SESSION_ASSURANCE_IDC_COOKIE_GRACEPE 
RIOD 


Description 


Specify the user-agent REGEX for that you want to 
disable the session validation. 


For example, see “Disabling Advanced Session 
Assurance for Access Gateway ESP” on page 938. 


Specify the URL for that you want to disable the 
session validation. 


For example, see “Disabling Advanced Session 
Assurance for Access Gateway ESP” on page 938. 


Specify the URL REGEX for that you want to disable 
the session validation. 


For example, see “Disabling Advanced Session 
Assurance for Access Gateway ESP” on page 938. 


Specify the time in second till which Identity Server will 
accept the old IDC cookie, after issuing a new cookie. 
The default value is 15 second. 


NOTE: After you configure an ESP option, you cannot revert it to the previous configuration by 
clicking Revert in the Cluster Configuration page (Access Gateway > Edit > Revert). 


Configuring Web Servers of a Proxy Service 


The web server configuration determines how Access Gateway handles connections and packets 


between itself and the web servers. 


IMPORTANT: For caching to work correctly, the web servers must be configured to maintain a valid 
time. They must be configured to use an NTP server. 


1 Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Web 


Servers. 


2 Specify the hostname that is placed in the HTTP header of the packets being sent to the web 
servers. In the Host Header field, select one of the following: 


+ Forward Received Host Name: Indicates that you want the HTTP header to contain the 
published DNS name that the user sent in the request. 


+ Web Server Host Name: Indicates that you want the published DNS name that the user 
sent in the request to be replaced by the DNS name of the web server. Use the Web Server 
Host Name field to specify this name. You can also append the port number to the Web 
Server Host Name field. For example, <web server hostname>:<web server port number>. 


3 Select Error on DNS Mismatch to have the proxy determine whether the proxy service must 
compare the hostname in the DNS header that came from the browser with the DNS name 
specified in the Web Server Host Name option. The value in the parentheses is the value that 


comes in the header from the browser. 


If you enable this option and the names don't match, the request is not forwarded to the web 
server. Instead, the proxy service returns an error to the requesting browser. This option is only 
available when you select to send the Web Server Host Name in the HTTP header. 
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NOTE: The Error on DNS Mismatch option does not work in the following scenarios: 
+ Ifthe option is enabled in a protected resource. 


+ Ifthe option is enabled in a master host based service, and disabled in a path-based child 
services, then Access Gateway does a strict check of DNS match for path-based child. 


If your browsers are capable of sending HTTP 1.1 requests, configure the following fields to 
match your web servers: 


Enable Force HTTP 1.0 to Origin: Indicates whether HTTP 1.1 requests from browsers are 
translated to HTTP 1.0 requests before sending them to the web server. If your browsers are 
sending HTTP 1.1 requests and your web server can only handle HTTP 1.0 requests, you must 
enable this option. 


When the option is enabled, Access Gateway translates an HTTP 1.1 request to an HTTP 1.0 
request. 


Enable Session Stickiness: Selecting this option makes the proxy server to use the same web 
server for all fills during a session. 


To enable SSL connections between the proxy service and its web servers, select Connect 
Using SSL. For configuration information for this option, Web Server Trusted Root, and SSL 
Mutual Certificate, see Section 17.6, “Configuring SSL between the Proxy Service and the Web 
Servers,” on page 995. 


In the Connect Port field, specify the port that Access Gateway must use to communicate with 
the web servers. The following table lists some default port values for common types of web 
servers. 


Server Type Non-Secure Port Secure Port 

Web server with HTML content 80 443 

WebSphere 9080 9443 

JBoss 8080 8443 

To control how idle and unresponsive web server connections are handled and to optimize these 


processes for your network, select TCP Connect Options. For more information, see 
“Configuring TCP Connect Options for Web Servers” on page 158. 


To add a web server, click New in the Web Server List and specify the IP address or the fully 
qualified DNS name of the web server. 


The web servers added to this list must contain identical web content. Configuring your system 
with multiple servers with the same content adds fault tolerance and increases the speed for 
processing requests. For more information about this process, see “Configuring Web Servers” 
on page 159. 


To delete a web server, select the web server, then click Delete. 


This deletes the web server from the list so that Access Gateway no longer sends requests to 
the deleted web server. At least one web server must remain in the list. You must delete the 
proxy service to remove the last server in the list. 


NOTE: Do not remove all configured web servers to the cluster if any of the cluster member 
does not have at least one web server configured. 


To save your changes to browser cache, click OK. 
To apply your changes, click the Access Gateways link, then click Update > OK. 
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3.8.4 


Configuring Protected Resources 


A protected resource configuration specifies the directory (or directories) on the web server that you 
want to protect. The protected resource configuration specifies the authorization procedures and the 
policies that must be used to enforce protection. The authentication procedures and the policies 
(Authorization, Identity Injection, and Form Fill) enable the single sign-on environment for the user. 
The type of protection a resource requires depends upon the resource, the web server, and the 
conditions you define for the resource. 


You can select from the following types of protection: 


Authentication Procedures: Specifies the type of credentials the user must use to log in (Such as 
name and password or secure name and password). You can select None for the procedure, which 
allows the resource to be a public resource, with no login required. 


In addition to selecting the contract, you can also configure how the authentication procedure handles 
subsequent authentication requests from an application. 


Authorization Policy: Specifies the conditions a user must meet to be allowed access to a protected 
resource. You define the conditions, and Access Gateway enforces the Authorization policies. For 
example, you can assign roles to your users, and use these roles to grant and deny access to 
resources. 


Identity Injection Policy: Specifies the information that must be injected into the HTTP header. If the 
web application has been configured to look for certain fields in the header and the information 
cannot be found, the web application determines whether the user is denied access or redirected. 
The web application defines the requirements for Identity Injection. The Identity Injection policies 
allow you to inject the required information into the header. 


Form Fill Policy: Allows you to manage forms that web servers return in response to client requests. 
Form fill allows you to prepopulate fields in a form on first login and then securely save the 
information in the completed form to a secret store for subsequent logins. The user is prompted to 
reenter the information only when something changes, such as a password. 


These policies allow you to design a custom access policy for each protected resource: 
+ Resources that share the same protection requirements can be configured as a group. You set 
up the policies, and then add the URLs of each resource that requires these policies. 


+ Aresource that has specialized protection requirements can be set up as a single protected 
resource. For example, a page that uses Form Fill is usually set up as a single protected 
resource. 


After configuring a protected resource, you can bookmark it. You cannot bookmark a login page that 
is used in a federation setup. 


To configure a protected resource: 
1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Domain-Based 
Proxy Service or Primary Proxy Service] > Protected Resources. 


The Resource View of the Protected Resource List is used to create new protected resources or 
manage existing protected resources. The Policy View is used to see which policies are being 
used by multiple protected resources. For more information about the Policy View, see 
“Assigning a Policy to Multiple Protected Resources” on page 138. 


2 Select one of the following actions: 


New: To create a new protected resource, click this option and specify a display name for the 
resource. For configuration information, see “Setting Up a Protected Resource” on page 129. 


Delete: To delete a protected resource, select a protected resource, then click Delete. 
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Enable: To enable a resource so that Access Gateway protects it, select a protected resource, 
then click Enable. 


Disable: To disable protection for a resource, select a protected resource, then click Disable. 
After a resource is disabled, its path no longer has special protection. For example, you can set 
up a resource that allows access to all pages (for example /*) and another resource with special 
protection for a subpath. If you disable the subpath, make sure the security requirements of the / 
* resource are sufficient for the subpath. 


Also, when a protected resource is disabled, the resource no longer shows up in the Path List for 
a path-based multi-homing proxy. 


3 Select the name of a protected resource to perform the following tasks: 
¢ “Configuring an Authentication Procedure for Non-Redirected Login” on page 132 
+ “Assigning an Authorization Policy to a Protected Resource” on page 133 
¢ “Assigning an Identity Injection Policy to a Protected Resource” on page 134 
+ “Assigning a Form Fill Policy to a Protected Resource” on page 135 
+ “Assigning a Timeout Per Protected Resource” on page 136 


3.8.4.1 Setting Up a Protected Resource 


1 Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > 
Protected Resources. 


2 Either click the name of an existing resource or click New, then specify a display name for the 
resource. 


3 (Optional) Specify a description for the protected resource. You can use it to briefly describe the 
purpose for protecting this resource. 


4 Select the type of contract to use for the authentication procedure. The contract determines the 
information a user must supply for authentication. By default, Administration Console allows you 
to select from the following contracts and options when specifying whether a resource requires 
an authentication contract: 


None: If you want to allow public access to the resource and not require an authentication 
contract, select None. 


Any Contract: If the user has authenticated, this option allows any contract defined for Identity 
Server to be valid, or if the user has not authenticated, it prompts the user to authenticate, using 
the default contract assigned to Identity Server configuration. 


Name/Password - Basic: Specifies basic authentication over HTTP, using a standard login pop- 
up provided by the web browser. 


Name/Password - Form: Specifies a form-based authentication over HTTP or HTTPS, using 
the Access Manager login form. 


Secure Name/Password - Basic: Specifies basic authentication over HTTPS, using a standard 
login pop-up provided by the web browser. 


Secure Name/Password - Form: Specifies a form-based authentication over HTTPS, using the 
Access Manager login form. 


The contract also determines the session timeout for inactive connections. If you have some 
resources that need to time out quickly to protect sensitive data and other resources that don’t 
need this kind of protection, you need to configure contracts for these resources. For more 
information about this feature, see “Assigning a Timeout Per Protected Resource” on page 136. 
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If no contracts are available, you have not configured a relationship between Access Gateway 
and Identity Server. See Section 3.8.2, “Managing Reverse Proxies and Authentication,” on 
page 119. 


(Conditional) To modify how the authentication procedures are handled for a specific resource 
and contract, click the Edit Authentication Procedures icon. 


For configuration information, see “Configuring an Authentication Procedure for Non-Redirected 
Login” on page 132. 


Configure the URL Path. 


The default path is /*, which indicates everything on the web server. Modify this if you need to 
restrict access to a specific directory on your web server. If you have multiple directories on your 
web server that require the same authentication contract and access control, add each directory 
as a URL path. 


New: To add a path, click New, specify the path, then click OK. For example, to allow access to 
all the pages in the public directory on the web server, specify the following path: 
/public/* 


To allow access to all the files in a directory, but not to the subdirectories and their files, specify 
the following: 

/? 

/public/? 

The /? allows access to the root directory, but not the subdirectories. The /public/? allows 
access to the files in the public directory, but not the subdirectories. 

To allow access to files of a specific type, specify the following: 

/public/* . pdf 

This allows access to all the files in the public directory that have a PDF extension. Access to 
other file types and subdirectories is denied. 

To use this protected resource to protect a single page, specify the path and the filename. For 
example, to protect the login. html page in the /login directory, specify the following: 
/login/login. html 


This is the type of URL path you want to specify when you create a Form Fill policy for a 
protected resource. The URL Path List normally contains only this one entry. If you have multiple 
pages that the Form Fill policy applies to, list each one separately in the list. For optimum speed, 
you want Access Gateway to be able to quickly identify the page and not search other pages to 
see if the policy applies to them. 


For more information about how a user’s request is matched to a protected resource, see 
“Understanding URL Path Matching” on page 131. 


For more information about using a query string, see “Using a Query String in the URL Path” on 
page 131. 


Modify: To modify a path, click the path link, then modify the URL Path. 
Delete: To delete a path, select the path, then click Delete. 


7 Click OK. 
8 In the Protected Resource List, ensure that the protected resource you created is enabled. 
9 (Optional) To add policies for protecting this resource, continue with one of the following: 


+ “Assigning an Authorization Policy to a Protected Resource” on page 133 
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¢ “Assigning an Identity Injection Policy to a Protected Resource” on page 134 
+ “Assigning a Form Fill Policy to a Protected Resource” on page 135 
+ “Assigning a Policy to Multiple Protected Resources” on page 138 


10 To apply your changes, click the Access Gateways link, then click Update > OK. 


Understanding URL Path Matching 


The URL path determines which protected resource is used for a user request. Suppose you create 
one protected resource with the following URL paths: 


L” 

/test/* 

/test/ 

You create a second protected resource with the following path: 
/test/*.php 

Users then send the following paths in their access requests: 


/test/ 
/test/1/2/3/file.php 
/file.php 

/test/file.php 
/test/file.php?param1=1234 


The first three requests (/test/, /test/1/2/3/file.php, and /file.php) match the first protected 
resource, and the last two requests (/test/file.php and /test/file.php?param1=1234) match the 
second protected resource. 


You then add the following URL path to the first protected resource: 

/test/? 

This URL path in the first protected resource causes all the requests to match the first protected 
resource, and the second protected resource is ignored. The ? wildcard, which matches all content in 
the current directory, takes precedence over the more specific wildcard (*.php). 

Using a Query String in the URL Path 

You can specify a query string in the URL path of a protected resource. For example: 

URL path: /test/index.html?test=test 


When the requested URL has a query string, Access Gateway searches for a protected resource with 
a matching URL path and query string. If it can’t find a match, the request returns a resource not 
found error. 


Access Gateway Appliance allows you to configure the URL matching process so that it ignores the 
query string in the URL path. Access Gateway Service does not have this option. If you want the 
query string ignored, you must remove it from the URL path of the protected resource. 
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3.8.4.2 


Configuring an Authentication Procedure for Non-Redirected Login 


When a contract is created, it is assigned an authentication procedure that allows the user to be 
redirected to Identity Server for authentication. Some applications, such as AJAX and WebDAV 
applications, do not support redirection for authentication. You can change the authentication 
behavior of a contract so that redirection does not occur. 


When non-redirected login is enabled, Access Gateway prompts the user to supply basic 
authentication credentials. The SOAP back channel between Access Gateway and Identity Server is 
used to complete the authentication on the user's behalf rather than a redirect. The SOAP back 
channel is also used for the session renewals. 


Non-redirected login has the following restrictions: 


¢ Password Expiration Services: When you modify the authentication procedures to use non- 
redirected login, you cannot also use a password expiration service. Even when the Password 
expiration servlet and Allow user interaction options are configured, users are not redirected 
when their passwords are expiring and they are not prompted to change their passwords. 


+ Locked Shared Secrets: When non-redirected login is enabled, users are not prompted for 
their passphrase for locked shared secrets. 


¢ Session Limits: Non-redirected login can cause the user to create more than one session with 
Identity Server because the SOAP back channel uses a different process than authentication 
requests that are directed to Identity Server. Therefore, do not limit your users to one session. 
Session limits are set by clicking Devices > Identity Servers > Edit. 


If the contract you are going to use for non-redirected login is also assigned to protected resources 
that do not require non-redirected login, you must create a new authentication procedure for the 
resource requiring non-redirected login. Multiple authentication procedures can be configured to use 
the same contract. 


To configure an authentication procedure: 
1 Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > 
Protected Resources > [Name of Protected Resource]. 
2 On the Authentication Procedure line, click the Edit Authentication Procedure icon. 


The Authentication Procedure List displays all available contracts, the name of the 
authentication procedure they are assigned to, the protected resources that the authentication 
procedure has been assigned to, and whether the procedure has been enabled for non- 
redirected login. 


3 Select one of the following actions: 


¢ To create an new authentication procedure, click New, specify a name, then click OK. 
Continue with Step 4. 


+ To modify an existing authentication procedure, click the name of the procedure. Continue 
with Step 4. 


+ To delete an existing authentication procedure, select the procedure, then click Delete. 
Continue with Step 7. 


If the procedure is used by a resource, it cannot be deleted until it is not being used to 
protect resources. An authentication procedure must exist for each contract. If you delete 
an authentication procedure for a contract without also deleting the contract, the system 
automatically re-creates an authentication procedure for the contract. 


4 To specify the method for obtaining the credentials, fill in the following fields: 
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Contract: Select the contract that you want to use for this protected resource. This needs to be 
a contract that supports basic authentication credentials such as Name/Password- Basic or 
Secure Name/Password-Basic. You can also configure Non-Redirected Login with a Kerberos 
contract. 


Non-Redirected Login: Select this option to use the SOAP back channel to verify the user’s 
credentials rather than a redirected request to Identity Server. 


Realm: Specify a name that your users can use to identify the site that they are authenticating 
to. This could be your company name or the name of the application. The realm is displayed as a 
heading when the application requests a basic authentication. 


Redirect to Identity Server When No Authentication Header Is Provided: The response 
must provide an authentication header. If the first request does not contain the authentication 
header, you can select this option to allow the first request to be redirected to Identity Server. 


5 Click OK. 


6 For the Authentication Procedure, select the authentication procedure you created or modified in 
Step 4. 


7 Click OK. 
8 Click Devices > Access Gateways, then update Access Gateway. 
9 (Optional) For some configuration scenarios that use this feature, see 
¢ “Configuring Protected Resource for a SharePoint Server’ on page 204 


+ “Configuring a Protected Resource for a SharePoint Server with an ADFS Server’ on 
page 210 


+ “Configuring a Protected Resource for Outlook Web Access” on page 213 
+ “Configuring a Protected Resource for a Novell Vibe 3.3 Server” on page 216 


Assigning an Authorization Policy to a Protected Resource 


An Authorization policy specifies conditions that a user must meet in order to access a resource. 
Access Gateway enforces these conditions. The policy can specify the criteria a user must meet 
either to allow access or to deny access. 


1 Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > 
Protected Resources > [Name of Protected Resource] > Authorization. 


The Authorization Policy List contains all Access Gateway Authorization policies that have been 
created on this Administration Console for the selected policy container. 


2 Select one of the following: 
+ To enable an existing policy, select the policy, then click Enable. Continue with Step 4. 
+ To disable an existing policy, select the policy, then click Disable. Continue with Step 4. 


+ To edit an existing policy, click the name of the policy. Remember that policies can be 
assigned to multiple protected resources. If you modify the policy, you are also affecting 
how this policy protects those resources. For configuration information, see Section 8.3, 
“Authorization Policies,” on page 760. 


When you have completed your policy modifications, continue with Step 4. 


+ To create a new policy, click Manage Policies. On the Policies page, click New, specify a 
display name, select Access Gateway: Authorization as the type, then click OK. For 
configuration information, see Section 8.3.2, “Creating Access Gateway Authorization 
Policies,” on page 771. 


When you have created your policy, continue with Step 3. 
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3 To enable the policy you just created, select the policy, then click Enable. 


Only the policies that are enabled are applied to this resource. All available Authorization policies 
are listed. If you use the same policy for multiple protected resources, use the policy description 
field to indicate this. 


4 To save your changes to the browser cache, click OK. 
5 To apply the changes, click the Access Gateways link, then click Update > OK. 


Assigning an Identity Injection Policy to a Protected Resource 


The web application defines the requirements for Identity Injection. If a web application has been 
configured to look for certain fields in the header and the information cannot be found, the web 
application determines whether the user is denied access, granted access, or redirected. You 
configure an Identity Injection policy to inject into the HTTP header the information that the web 
application requires. 


1 Click Access Gateways > Edit > [Reverse Proxy Name] > [Name of Proxy Service] > Protected 
Resources > [Name of Protected Resource] > Identity Injection. 


The Identity Injection Policy List contains all the Identity Injection policies that have been 
created on this Administration Console for the selected policy container. 


2 Select one of the following: 


+ To enable an existing policy, select the policy, then click Enable. Only the policies that are 
enabled are applied to this resource. Continue with Step 4. 


+ To disable an existing policy, select the policy, then click Disable. Continue with Step 4. 


+ To edit an existing policy, click the name of the policy. Remember that policies can be 
assigned to multiple protected resources. If you modify the policy, you are also affecting 
how this policy protects those resources. For configuration information, see Chapter 8.4, 
“Identity Injection Policies,” on page 810. 


When you have finished your policy modifications, continue with Step 4. 


+ To create a new policy, click Manage Policies. On the Policies page, click New, specify a 
display name, select Access Gateway: Identity Injection as the type, then click OK. For 
configuration information, see Chapter 8.4, “Identity Injection Policies,” on page 810. 


When you have created your policy, continue with Step 3. 
3 To enable the policy you just created, select the policy, then click Enable. 


Only the policies that are enabled are applied to this resource. If you use the same policy for 
multiple protected resources, use the policy description field to indicate this. 


4 To save your changes to the browser cache, click OK. 
5 To apply your changes, click the Access Gateways link, then click Update > OK. 


IMPORTANT: If you enable an Identity Injection policy for a protected resource that has been 
assigned to use a contract that does not prompt the user for a password and the Identity Injection 
policy injects the user’s password, single sign-on cannot be enabled because the password is not 
available. However, you can create a contract that retrieves the user’s password when the user is not 
prompted for a password when authenticating. See Section 5.1.11, “Password Retrieval,” on 

page 406. 


134 Setting Up a Basic Access Manager Configuration 


3.8.4.5 


Assigning a Form Fill Policy to a Protected Resource 


Some client requests cause the web server to return a form. Sometimes this form contains a request 
to log in. If you create a Form Fill policy, you can have Access Gateway fill in the form. When a user 
first logs in, Access Gateway prepopulates some fields and prompts the users for the others. Access 
Gateway securely saves the information, so that on subsequent logins, Access Gateway can fill in the 
form. The user is only prompted to fill in the form when something changes, such as a password 
expiring. 


Form Fill uses two components: the HTML form and the Form Fill policy. The HTML form is created 
with HTML tags and consists of form elements such as fields, menus, check boxes, and buttons. The 
Form Fill policy is created by specifying the following: 
¢ Which information is entered automatically and not displayed to the user. 
+ Which information is displayed so that the user, at least the first time, can enter the information. 
¢ What is done with the information (for example, whether it is saved so that the user does not 
need to enter it when accessing the form again). 


You must create the policy before you can assign it to a resource (see Chapter 8.5, “Form Fill 
Policies,” on page 831). To assign a Form Fill policy to a protected resource: 


1 Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Name of Proxy Service] > 
Protected Resources > [Name of Protected Resource]. 
2 Examine the entries in the URL Path List. 


Ideally, the URL to which you are assigning a Form Fill policy must be a single HTML page ora 
few HTML pages. If possible, it must not be a URL that ends in a wildcard (for example, an 
asterisk) and therefore matches many pages. 


IMPORTANT: When the URL ends in a wildcard, Access Gateway must search each page that 
matches the URL and check to see if it contains the form. This adds extra processing overhead 
for all the pages that match the URL, but do not contain the form. For more information about the 
performance problems this can cause, see Chapter 8.5, “Form Fill Policies,” on page 831. 

3 (Conditional) If the URL is not specific, click the name of the path and modify it. 

4 Click Form Fill. 


The Form Fill Policy List contains all the Form Fill policies that have been created on this 
Administration Console for the selected policy container. 


5 Select one of the following: 


+ To enable an existing policy, select the policy, then click Enable. Only the policies that are 
enabled are applied to this resource. Continue with Step 7. 


+ To disable an existing policy, select the policy, then click Disable. Continue with Step 7. 


+ To edit an existing policy, click the name of the policy. Remember that policies can be 
assigned to multiple protected resources. If you modify the policy, you are also affecting 
how this policy protects those resources. For configuration information, see Chapter 8.5, 
“Form Fill Policies,” on page 831. 


When you have finished the policy modifications, continue with Step 7. 


+ To create a new policy, click Manage Policies. On the Policies page, click New, specify a 
display name, select Access Gateway: Form Fill as the type, then click OK. For 
configuration information, see Chapter 8.5, “Form Fill Policies,” on page 831. 


When you have created your new policy, continue with Step 6. 
6 To enable the policy you just created, select the policy, then click Enable. 
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3.8.4.6 


Only the policies that are enabled are applied to this resource. If you use the same policy for 
multiple protected resources, use the policy description field to indicate this. 


7 To save your changes to the browser cache, click OK. 
8 To apply your changes, click the Access Gateways link, then click Update > OK. 


IMPORTANT: If you enable a Form Fill policy for a protected resource that has been assigned to use 
a contract that does not prompt the user for a password and the Form Fill policy contains a field for 
the user’s password, single sign-on cannot be enabled because the password is not available. To 
enable single sign-on, you need to use an Authentication class that retrieves the user’s password and 
injects it into the user’s credentials when the user authenticates using a non-password method such 
as X.509, RADIUS, smart card, or Kerberos. For information about such a class, see Section 5.1.11, 
“Password Retrieval,” on page 406. 


Assigning a Timeout Per Protected Resource 


If all your resources are using the same contract and you want them all to have the same timeout for 
inactivity, you set the Authentication Timeout option on the contract to the required limit and leave 
the Activity Realm option blank. The user logs in, and activity by the user on any resource keeps the 
user's session active. The user is prompted to reauthenticate only when the user has no activity on 
any resources for longer than the authentication timeout value. 


If you have some resources that require a shorter timeout than other resources, you need to balance 
the need for single sign-on with the timeout requirements: 


¢ To strictly enforce a timeout, the resource needs to be assigned to a custom contract. 
+ To preserve single sign-on, resources need to be assigned to the same contract. 


The protected resource is assigned to use a contract, and the timeout is assigned to the contract. For 
information about how to configure the contract, see Section 5.1.4, “Configuring Authentication 
Contracts,” on page 379. 


The following sections describe four configuration scenarios and the user experience that they 
create. 


Scenario 1: If strictly adhering to the timeout value is more important than preserving the session or 
single sign-on, configure your resources as follows: 


+ Protected resource 1 (PR1) is configured to use contract 1 (C1), which has been created from 
method 1 (M1) and placed in its own activity realm (AR1). For this scenario you set the 
authentication timeout to 30 minutes. 


+ Protected resource 2 (PR2) is configured to use contract 2 (C2), which has been created from 
method 2 (M2) and placed in its own activity realm (AR2). For this scenario, you set the 
authentication timeout to 15 minutes. 


With this scenario, the user is prompted to log in when accessing PR1 and when accessing PR2. 
Each resource has its own time line, because each resource belongs to its own activity realm. Figure 
3-7 The figure below illustrates this scenario. 
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Figure 3-7 Login Requirements with Separate Methods and Separate Activity Realms 
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After authenticating to both resources and remaining active on both resources for the first 10 minutes, 
the sessions remain active. The user then stays active on PR1 without accessing PR2 for over 15 
minutes. The AR1 time line is updated with this activity. The AR2 time line is not updated. When the 
user accesses PR2 after more than 15 minutes of inactivity on the AR2 time line, the user is prompted 
to authenticate. The user then returns to PR1 after over 20 minutes of inactivity, but AR1 time line 
shows activity within the 30-minute timeout. The user is granted access and does not need to log in 
again to access PR1. 


In this scenario, the resources are independent of each other and do not influence each other’s 
timeout limits. 


Scenario 2: If you are willing to allow a resource to influence the timeout of another resource, 
configure your resources as follows: 


+ Protected resource 1 (PR1) is configured to use contract 1 (C1), which has been created from 
method 1 (M1) and placed in a shared activity realm (Shared1). For this scenario you set the 
authentication timeout to 30 minutes. 


+ Protected resource 2 (PR2) is configured to use contract 2 (C2), which has been created from 
method 2 (M2) and placed in a shared activity realm (shared1). For this scenario, you set the 
authentication timeout to 15 minutes. 


With this scenario, the user is prompted to log in when accessing PR1 and when accessing PR2. 
Activity at either resource updates the shared1 time line. Figure 3-8 illustrates this scenario. 


Figure 3-8 Login Requirements for Separate Methods with a Shared Activity Realm 
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As long as the user is active on PR1, the user’s session to PR2 remains active. After 20 minutes of 
activity on PR1, the user returns to PR2. The user is allowed access and does not need to log in 
because the shared1 time line shows activity within the last 5 minutes. The user remains active on 
PR2 for over 30 minutes, then accesses PR1. Again, the shared1 time line shows activity within the 
last 5 minutes, so the user is granted access to PR1 without logging in again. 


With this configuration, activity at other resources influences the time limits so that they are not strictly 
enforced. 


Scenario 3: If single sign-on is more important than strictly enforcing a timeout value, NetIQ 
recommends that you configure all contracts to have the same authentication timeout value. 
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3.8.4.7 


If you configure your resources as follows, you might not get the behavior you require: 


+ Protected resource 1 (PR1) is configured to use contract 1 (C1), which has been created from 
method 1 (M1) and placed in a shared activity realm (Shared1). For this scenario you set the 
authentication timeout to 30 minutes. 


¢ Protected resource 2 (PR2) is configured to use contract 2 (C2), which has been created from 
method 1 (M1) and placed in a shared activity realm (shared1). For this scenario, you set the 
authentication timeout to 15 minutes. 


Because C1 and C2 are created from the same method (M1), the user does not need to log in twice 
to access both resources. Logging in to one resource allows them access to the other resource. 
Figure 3-9 illustrates this scenario. 


Figure 3-9 Login Requirements for Shared Methods and Shared Realms 
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The user first logs in to PR2 and is active for 10 minutes. The shared1 time line gets updated with this 
activity. When the user requests access to PR1, the user is granted access without being prompted 
for credentials. The user is then active on PR1 for over 20 minutes. When the user requests access to 
PR2, even though the user has been inactive on this resource for over 20 minutes, the user is granted 
access because the time line shows activity within the last five minutes. 


With this configuration, PR2 does not time out as long as the user remains active on PR1. However, 
when the user goes inactive on both PR2 and PR1 for over 15 minutes and the user requests access 
to PR1, the time line shows no activity within the time limit specified for PR2 and the user is prompted 
to log in. 


Scenario 4: NetIQ does not recommend that you set different authentication timeouts on contracts 
and then use the Any contract option for protected resources. If you want to use the Any contract, 
then you must set the authentication timeout to the same value on all contracts. If the timeouts are not 
the same, you cannot consistently predict what timeouts are being applied to the various protected 
resources. For example, the user requests access to a resource that is protected with a contract with 
a short timeout. The user logs in, then accesses resources that use the Any contract option. All of 
these resources are assigned a short timeout.The user then goes inactive and the session times out. 
The user then requests access to a resource with a contract with a long timeout. The user logs in, and 
after a few minutes, accesses same resources protected with the Any contract option. These 
resources are now assigned the long timeout value. 


Assigning a Policy to Multiple Protected Resources 


If you have created multiple protected resources that need to be protected by the same policy or 
policies, you can use the policy view to assign a policy to multiple protected resources. However, the 
protected resources must belong to the same proxy service. 


1 Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Name of Proxy Service] > 
Protected Resources. 


2 Select the Policy View. 
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3 Select the Used By link of the policy you want to assign to multiple resources. 


The Policy and Policy Container fields identify the policy. The Protected Resource Policy Usage 
List displays the protected resources defined for this proxy service and indicates which 
resources the policy has been enabled on. 


4 To enable the policy for multiple resources, either select them one by one or click Name to select 
all of them, then click Enable. To disable a policy for a resource, select the resource, then click 
Disable. 


5 To save your changes to browser cache, click OK. 
6 To apply your changes, click the Access Gateways link, then click Update > OK. 


3.8.5 Configuring HTML Rewriting 


Access Gateway configurations generally require HTML rewriting because the web servers are not 
aware that Access Gateway machine is obfuscating their DNS names. URLs contained in their pages 
must be checked to ensure that these references contain the DNS names that the client browser 
understands. On the other end, the client browsers are not aware that Access Gateway is obfuscating 
the DNS names of the resources they are accessing. 


The URL requests coming from the client browsers that use published DNS names must be rewritten 
to the DNS names that the web servers expect. Figure 3-10 illustrates these processes. 


Figure 3-10 HTML Rewriting 
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The following sections describe the HTML rewriting process: 


HTML 
Rewriter 


<HTML> 
<img src=http://data.com/image1.jpg/> 
</HTML> 


¢ Section 3.8.5.1, “Understanding the Rewriting Process,” on page 139 

¢ Section 3.8.5.2, “Specifying DNS Names to Rewrite,” on page 141 

¢ Section 3.8.5.3, “Defining the Requirements for the Rewriter Profile,” on page 144 
¢ Section 3.8.5.4, “Configuring the HTML Rewriter and Profile,” on page 151 

¢ Section 3.8.5.5, “Creating or Modifying a Rewriter Profile,” on page 153 

¢ Section 3.8.5.6, “Disabling the Rewriter,” on page 154 


3.8.5.1 Understanding the Rewriting Process 


Access Gateway needs to rewrite URL references under the following conditions: 


¢ To ensure that URL references contain the proper scheme (HTTP or HTTPS). 
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+ 


If your web servers and Access Gateway machines are behind a secure firewall, you might not 
require SSL sessions between them, and only require SSL between the client browser and 
Access Gateway. For example, an HTML file being accessed through Access Gateway for the 
website novell.com might have a URL reference to http: //novell.com/path/image1. jpg. If 
the reverse proxy for novell.com/path is using SSL sessions between the browser and Access 
Gateway, the URL reference http: //novell.com/path/image1.jpg must be rewritten to 
https://novell.com/path/image1.jpg. Otherwise, when the user clicks the HTTP link, the 
browser must change from HTTP to HTTPS and establish a new SSL session. 


To ensure that URL references containing private IP addresses or private DNS names are 
changed to the published DNS name of Access Gateway or hosts. 


For example, suppose that a company has an internal website named data.com, and wants to 
expose this site to Internet users through Access Gateway by using a published DNS name of 
novell.com. Many of the HTML pages on this website have URL references that contain the 
private DNS name, such as http://data.com/imagel. jpg. Because Internet users are unable 
to resolve data.com/imagel. jpg, links using this URL reference would return DNS errors in the 
browser. 


The HTML rewriter can resolve this issue. The DNS name field in Access Gateway configuration 
is set to novell.com, which users can resolve through a public DNS server to Access Gateway. 
The rewriter parses the web page, and any URL references matching the private DNS name or 
private IP address listed in the web server address field of Access Gateway configuration are 
rewritten to the published DNS name novell.com and the port number of Access Gateway. 


Rewriting URL references addresses two issues: 1) URL references that are unreachable 
because of the use of private DNS names or IP addresses are now made accessible and 2) 
Rewriting prevents the exposure of private IP addresses and DNS names that might be sensitive 
information. 


To ensure that the Host header in incoming HTTP packets contains the name understood by the 
internal web server. 


Using the example in Figure 3-10 on page 139, suppose that the internal web server expects all 
HTTP or HTTPS requests to have the Host field set to data.com. When users send requests 
using the published DNS name novell.com/path, the Host field of the packets in those 
requests received by Access Gateway is set to novell.com. Access Gateway can be configured 
to rewrite this public name to the private name expected by the web server by setting the Web 
Server Host Name option to data.com. Before Access Gateway forwards packets to the web 
server, the Host field is changed (rewritten) from novell.com to data.com. For information 
about configuring this option, see Section 3.8.3, “Configuring Web Servers of a Proxy Service,” 
on page 126. 


The rewriter searches for URLs in the following HTML contexts. They must meet the following criteria 
to be rewritten: 


Context Criteria 


HTTP Headers Qualified URL references occurring within certain types of HTTP response headers 


such as Location and Content-Location are rewritten. The Location header is used 
to redirect the browser to where the resource can be found. The Content-Location 
header is used to provide an alternate location where the resource can be found. 


JavaScript Within JavaScript, absolute references are always evaluated for rewriting. Relative 


references (such as index.html) are not attempted. Absolute paths (such as / 
docs/file.htm1) are evaluated if the page is read from a path-based multi-homing 
web server and the reference follows an HTML tag. For example, the string 
href='/docs/file.htm1' is rewritten if /docs is a multi-homing path that has 
been configured to be removed. 
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3.8.5.2 


Context Criteria 


HTML Tags URL references occurring within the following HTML tag attributes are evaluated for 
rewriting: 
action archive background 
cite code codebase 
data dynscr filterLink 
href longdesc lowsrc 
o:WebQuerySourceHref onclick onmenuclick 
pluginspage src usemap 
usermapborderimage 

References An absolute reference is a reference that has all the information needed to locate a 


resource, including the hostname, such as http://internal.web.site.com/ 
index.html. The rewriter always attempts to rewrite absolute references. 


The rewriter attempts to rewrite an absolute path when it is the multi-homing path of 
a path-based multi-homing service. For example, /docs/file1.html is rewritten if 
/docs is a multi-homing path that has been configured to be removed. 


Relative references are not rewritten. 


Query Strings URL references contained within query strings can be configured for rewriting by 
enabling the Rewrite Inbound Query String Data option. 


Post Data URL references specified in Post Data can be configured for rewriting by enabling 
the Rewrite Inbound Post Data option. 


Specifying DNS Names to Rewrite 


The rewriter parses and searches the web content that passes through Access Gateway for URL 
references that qualify to be rewritten. URL references are rewritten when they meet the following 
conditions: 


¢ URL references containing DNS names or IP addresses matching those in the web server 
address list are rewritten with the Published DNS Name. 


+ URL references matching the Web Server Host Name are rewritten with the Published DNS 
Name. 


¢ URL references matching entries in the Additional DNS Name List of the host are rewritten with 
the Published DNS Name. The Web Server Host Name does not need to be included in this list. 


+ The DNS names in the Exclude DNS Name List specify the names that the rewriter must skip 
and not rewrite. 


NOTE: Excludes in the Exclude DNS Name List are processed first, then the includes in the 
Additional DNS Name List. If you put the same DNS name in both lists, the DNS name is rewritten. 


The following sections describe the conditions to consider when adding DNS names to the lists: 


+ “Determining Whether You Need to Specify Additional DNS Names” on page 142 
¢ “Determining Whether You Need to Exclude DNS Names from Being Rewritten” on page 143 
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Determining Whether You Need to Specify Additional DNS Names 


Sometimes web pages contain URL references to a hostname that does not meet the default criteria 
for being rewritten. That is, the URL reference does not match the Web Server Host Name or any 
value (IP address) in the Web Server List. If these names are sent back to the client, they are not 
resolvable. Figure 3-11 illustrates a scenario that requires an entry in the Additional DNS Name List. 


Figure 3-11 Rewriting a URLs for Web Servers 
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The page on the data.com web server contains two links, one to an image on the data.com server 
and one to an image on the graphics.com server. The link to the data. com server is automatically 
rewritten to novell.com, when rewriting is enabled. The link to the image on graphics.com is not 
rewritten, until you add this URL to the Additional DNS Name List. When the link is rewritten, the 
browser knows how to request it, and Access Gateway knows how to resolve it. 


You need to include names in this list if your web servers have the following configurations: 


+ If you have a cluster of web servers that are not sharing the same DNS name, you need to add 
their DNS names to this list. 


¢ If your web server obtains content from another web server, the DNS name for this additional 
web server needs to be added to the list. 


+ |f the web server listens on one port (for example, 80), and redirects the request to a secure port 
(for example, 443), the DNS name needs to be added to the list. The response to the user 
comes back on https://<DNS_name>: 443. This does not match the request that was sent on 
http: //<DNS_name>:80. If you add the DNS name to the list, the response can be sent in the 
format that the user expects. 


¢ If an application is written to use a private hostname, you need to add the private hostname to 
the list. For example, assume that an application URL reference contains the hostname of home 
(http: //home/index.html). This hostname needs to be added to the Additional DNS Name 
List. 


+ If you enable the Forward Received Host Name option on your path-based multi-homing service 
and your web server is configured to use a different port, you need to add the DNS name with 
the port to the Additional DNS Name List. 
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For example, if the public DNS name of the proxy service is www.myag.con, the path for the path- 
based multi-homing service is /sales, and the web server port is 801, the following DNS name 
needs to be added to the Additional DNS Name List of the /sales service: 


http://www.myag.com: 801 
When you enter a name in the list, it can use any of the following formats: 


DNS_name 

host_name 

IP_address 

scheme: //DNS_name 
scheme: //IP_address 
scheme: //DNS_name:port 
scheme: //IP_address:port 


For example: 


HOME 
https://www.backend.com 
https://10.10.15.206:444 


These entries are not case sensitive. 


Determining Whether You Need to Exclude DNS Names from Being Rewritten 


If you have two reverse proxies protecting the same web server, the rewriter correctly rewrites the 
references to the web server so that browser always uses the same reverse proxy. In other words, if 
the browser requests a resource using novell.com.uk, the response is returned with references to 
novell.com.uk and not novell.com.usa. 


If you have a third reverse proxy protecting a web server, the rewriting rules can become ambiguous. 
For example, consider the configuration illustrated in Figure 3-12. 


Figure 3-12 Excluding URLs 
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3.8.5.3 


A user accesses data.com through the published DNS name of novell.com.mx. The data.com 
server has references to product.com. The novell.com.mx proxy has two ways to get to the 
product .com server because this web server has two published DNS names (novell.com.uk and 
novell.com.usa). The rewriter could use either of these names to rewrite references to 

product .com. 


¢ If you want all users coming through novell.com.mx to use the novell.com.usa proxy, you 
need to block the rewriting of product . com to novell.com.uk. On the HTML Rewriting page of 
the reverse proxy for novell.com.uk, add product .com and any aliases to the Exclude DNS 
Name List. 


+ If you do not care which proxy is returned in the reference, you do not need to add anything to 
the Exclude DNS Names List. 


Defining the Requirements for the Rewriter Profile 


An HTML rewriter profile allows you to customize the rewriting process and specify the profile that is 
selected to rewrite content on a page. This section describes the following features of the rewriter 
profile: 

e “Types of Rewriter Profiles” on page 144 

e “Page Matching Criteria for Rewriter Profiles” on page 145 

¢ “Possible Actions for Rewriter Profiles” on page 146 

¢ “String Replacement Rules for Word Profiles” on page 148 

¢ “String Tokens” on page 148 

¢ “String Replacement Rules for Character Profiles” on page 149 

¢ “Using $path to Rewrite Paths in JavaScript Methods or Variables” on page 150 


Types of Rewriter Profiles 
Access Gateway has the following types of profiles: 


+ Default Word Profile 
+ Custom Word Profile 


+ Custom Character Profile 


Default Word Profile 
The default Word profile, named default, is not specific to a reverse proxy or its proxy services. 


If you enable HTML rewriting, but you do not define a custom Word profile for the proxy service, the 
default Word profile is used. This profile is preconfigured to rewrite the Web Server Host Name and 
any other names listed in the Additional DNS Name List. The preconfigured profile matches all URLs 
with the following content-types: 


text/html text/javascript 
text/xml application/javascript 
text/css application/x-javascript 


When you modify the behavior of the default profile, remember its scope. If the default profile does 
not match your requirements, you must usually create your own custom Word profile or custom 
Character profile. 
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Custom Word Profile 


A Word profile searches for matches on words. For example, “get” matches the word “get” and any 
word that begins with “get” such as “getaway” but it does not match the “get” in “together” or “beget.” 


For information about how strings are replaced in a Word profile, see the following: 


¢ “String Replacement Rules for Word Profiles” on page 148 
¢ “Using $path to Rewrite Paths in JavaScript Methods or Variables” on page 150 


You must create a custom Word profile when an application requires rewrites of paths in JavaScript. If 
the application needs strings replaced or new content-types, these can also be added to the custom 
profile. In a custom Word profile, you can also configure the match criteria so that the profile matches 
specific URLs. For more information, see “Page Matching Criteria for Rewriter Profiles” on page 145. 


When you create a custom Word profile, you need to position it before the default profile in the list of 
profiles. Only one Word profile is applied per page. The first Word profile that matches the page is 
applied. Profiles lower in the list are ignored. 


Custom Character Profile 


A custom Character profile searches for matches on a specified set of characters. For example, “top” 
matches the word “top” and the “top” in “tabletop,” “stopwatch,” and “topic.” If you need to replace 
strings that require this type of search, you must create a custom Character profile. 


For information about how strings are replaced in a Character profile, see “String Replacement Rules 
for Character Profiles” on page 149. 


In a custom Character profile, you can also configure the match criteria so that the profile matches 
specific URLs. For more information, see “Page Matching Criteria for Rewriter Profiles” on page 145. 


After the rewriter finds and applies the Word profile that matches the page, it finds and applies one 
Character profile. The first Character profile that matches the page is applied. Character profiles 
lower in the list are ignored. 

Page Matching Criteria for Rewriter Profiles 


You specify the following matching criteria for selecting the profile: 


+ The URLs to match 
+ The URLs that cannot match 
+ The content types to match 


You use the Requested URLs to Search section of the profile to set up the matching policy. The first 
Word profile and the first Character profile that matches the page is applied. Profiles lower in the list 
are ignored. 


URLs: The URLs specified in the policy must use the following formats: 
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Sample URL Description 


http: //www.a.com/content Matches pages only if the requested URL does not 
contain a trailing slash. 


http://www.a.com/content/ Matches pages only if the requested URL does 
contain a trailing slash. 

http://www.a.com/content/index. html Matches only this specific file. 

http://www.a.com/content/* Matches the requested URL whether it has a 
trailing slash and matches all files in the directory. 

http: //www.a.com/* Matches the proxy service and everything it is 
protecting. 


You can specify two types of URLs. In the If Requested URL Is list, you specify the URLs of the pages 
you want this profile to match. In the And Requested URL Is Not list, you specify the URLs you don’t 
want this profile to match. You can use the asterisk wildcard for a URL in the If Requested URL Is list 
to match pages you really don’t want this profile to match, then use a URL in the And Requested URL 
Is Not list to exclude them from matching. If a page matches both a URL in the If Requested URL Is 
list and in the And Requested URL Is Not list, the profile does not match the page. 


For example, you could specify the following URL in the If Requested URL Is list: 
http: //www.a.com/* 

You could then specify the following URL in the And Requested URL Is Not list: 
http: //www.a.com/content/* 


These two entries cause the profile to match all pages on the www. a.com web server except for the 
pages in the /content directory and its subdirectories. 


IMPORTANT: If nothing is specified in either of the two lists, the profile skips the URL matching 
requirements and uses the content-type to determine if a page matches. 


Content-Type: In the And Document Content-Type Is section, you specify the content-types you 
want this profile to match. To add a new content-type, click New and specify the name, such as text/ 
dns. Search your web pages for content-types to determine if you need to add new types. To add 
multiple values, enter each value on a separate line. 


Regardless of content-types you specify, the page matches the profile if the file extension is html1, 
htm, shtml, jhtml, asp, or jsp and you have not specified any URL matching criteria. 
Possible Actions for Rewriter Profiles 


The rewriter action section of the profile determines the actions the rewriter performs when a page 
matches the profile. Select from the following: 


¢ Inbound Actions 
¢ Enabling or Disabling Rewriting 
¢ Additional Names to Search for URL Strings to Rewrite with Host Name 


¢ String Replacement 
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Inbound Actions: A profile might require these options if the proxy service has the following 
characteristics: 


+ URLs appear in query strings, Post Data, or headers. 
+ The web server uses WebDAV methods. 


If your profile needs to match pages from this type of proxy service, you might need to enable the 
options listed below. They control the rewriting of query strings, Post Data, and headers from Access 
Gateway to the web server. 


¢ Rewrite Inbound Query String Data: Select this option to rewrite the domain and URL in the 
query string to match the web server configuration or to remove the path from the query string on 
a path-based multi-homing proxy with the Remove Path on Fill option enabled. 


+ Rewrite Inbound Post Data: Select this option to rewrite the domain and URL in the Post Data 
to match the web server configuration or to remove the path from the Post Data on a path-based 
multi-homing proxy with the Remove Path on Fill option enabled. 


¢ Rewrite Inbound Headers: Select this option to rewrite the following headers: 


Call-Back 
Destination 

If 
Notification-Type 
Referer 


The inbound options are not available for a Character profile. 


Enabling or Disabling Rewriting: The Enable Rewriter Actions option determines whether the 
rewriter performs any actions: 


¢ Select the option to have the rewriter rewrite the references and data on the page. 


+ Leave the option deselected to disable rewriting. This allows you to create a profile for the pages 
you do not want rewritten. 


Additional Names to Search for URL Strings to Rewrite with Host Name: Use this section to 
specify the name of the variable, attribute, or method in which the hostname might appear. These 
options are not available for a Character profile. 


¢ Variable and Attribute Name to Search for Is: Use this section to specify the HTML attributes 
or JavaScript variables that you want searched for DNS names that might need to be rewritten. 
For the list of HTML attribute names that are automatically searched, see “HTML Tags” on 
page 141. You might want to add the following attributes: 


¢ value: This attribute enables the rewriter to search the <param> elements on the HTML 
page for value attributes and rewrite the value attributes that are URL strings. 


If you need more granular control (some need to be rewritten but others do not) and you can 
modify the page, see “Disabling with Page Modifications” on page 155. 


+ formvalue: This attribute enables the rewriter to search the <form> element on the HTML 
page for <input>, <button>, and <option> elements and rewrite the value attributes that 
are URL strings. For example, if your multi-homing path is /test and the form line is 
<input name="navUrl" type="hidden" value="/IDM/portal/cn/ 
GuestContainerPage/656gwmail">, this line would be rewritten to the following value 
before sending the response to the client: 
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<input name="navUrl" type="hidden" value="/test/IDM/portal/cn/ 
GuestContainerPage/656gwmail"> 


The formvalue attribute enables the rewriting of all URLs in the <input>, <button>, and 
<option> elements in the form.If you need more granular control (some need to be 
rewritten but others do not) and you can modify the form page, see “Disabling with Page 
Modifications” on page 155. 


¢ Replacing URLs in Java Methods: The JavaScript Method to Search for Is list allows you to 
specify the Java methods to search to see if their parameters contain a URL string. 


String Replacement: The Additional Strings to Replace list allows you to search for a string and 
replace it. The search boundary (word or character) that you specified when creating the profile is 
used when searching for the string. 


Word profile search and replace actions take precedence over character profile actions. 
For the rules and tokens that can be used in the search strings, see the following: 


¢ “String Replacement Rules for Word Profiles” on page 148 
¢ “String Tokens” on page 148 
¢ “String Replacement Rules for Character Profiles” on page 149 


For information about how the Additional Strings to Replace list can be used to reduce the number of 
Java methods you need to list, see “Using $path to Rewrite Paths in JavaScript Methods or Variables” 
on page 150. 


String Replacement Rules for Word Profiles 


In a Word profile, a string matches all paths that start with the characters in the specified string. For 
example: 


Search String Matches This String Does not’ Match This String 
/path /path /mypath 

/pathother 

/path/other 

/path. html 


String Tokens 


On Access Gateway Service, you can use the following special tokens to modify the default matching 
rules. Access Gateway Appliance does not support these tokens. 

¢ [w] to match one white space character 

+ [ow] to match 0 or more white space characters 

¢ [ep] to match a path element in a URL path, excluding words that end in a period 

¢ [ew] to match a word element in a URL path, including words that end in a period 

+ [oa] to match one or more alphanumeric characters 


White Space Tokens: You use the [w] and the [ow] tokens to specify where white space might occur 
in the string. For example: 


[ow]my[w]string[w]to[w]replace[ow] 
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If you don’t know, or don’t care, whether the string has zero or more white characters at the beginning 
and at the end, use [ow] to specify this. The [w] specifies exactly one white character. 


Path Tokens: You use the [ep] and [ew] tokens to match path strings. The [ep] token can be used to 
match the following types of paths: 


Search String Matches This String Does not’ Match This String 
/path[ep] /path /path. html 
/home/path/other /home/pathother 


The [ew] token can be used to match the following types of paths: 


Search String Matches This String Does not Match This String 
/path[ew] /path. html /paths 
/home/path 


Name Tokens: You use the [oa] token to match function or parameter names that have a set string to 
start the name and end the name, but the middle part of the name is a computer-generated 
alphanumeric string. For example, the [oa] token can be used to match the following types of names: 


Search String Matches This String Does not’ Match This String 


javaFunction- [oa] ( javaFunction-1234a56( ) javaFunction() 


javaFunction-a() 


String Replacement Rules for Character Profiles 


When you configure multiple strings for replacement, the rewriter uses the following rules for 
determining how characters are replaced in strings: 
¢ String replacement is done as a single pass. 
¢ String replacement is not performed recursively. Suppose you have listed the following search 
and replacement strings: 


DOG to be replaced with CAT 
A to be replaced with (0) 


All occurrences of the string DOG are replaced with CAT, regardless of whether it is the word 
DOG or the word DOGMA. Only one replacement pass occurs. The rewritten CAT is not 
replaced with COT. 


+ Because string replacement is done in one pass, the string that matches first takes precedence. 
Suppose you have listed the following search and replacement strings: 


ABC to be replaced with XYZ 
BCDEF to be replaced with PQRSTUVWXYZ 


If the original string is ABCDEFGH, the replaced string is XYZDEFGH. 


¢ If two specified search strings match the data portion, the search string of longer length is used 
for the replacement except for the case detailed above. Suppose you have listed the following 
search and replacement strings: 
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ABC to be replaced with XYZ 
ABCDEF to be replaced with PQRSTUVWXYZ 


If the original string is ABCDEFGH, the replaced string is PARSTUVWXYZGH. 


Using $path to Rewrite Paths in JavaScript Methods or Variables 


You can use the $path token to rewrite paths on a path-based multi-homing service that has the 
Remove Path on Fill option enabled. This token is useful for web applications that require a dedicated 
web server and are therefore installed in the root directory of the web server. If you protect this type of 
application with Access Manager using a path-based multi-homing service, your clients access the 
application with a URL that contains a /path value. The proxy service uses the path to determine 
which web server a request is sent to, and the path must be removed from the URL before sending 
the request to the web server. 


The application responds to the requests. If it uses JavaScript methods or variables to generate paths 
to resources, these paths are sent to client without prepending the path for the proxy service. When 
the client tries to access the resource specified by the web server path, the proxy service cannot 
locate the resource because the multi-homing path is missing. The figure below illustrates this flow 
with the rewriter adding the multi-homing path in the reply. 


Figure 3-13 Rewriting with a Multi-homing Path 


Firewall 
Browsers Access Web 
Gateway Server 
[ inner.com 
L] = IM 
7 Request 
d 


ae novell.com 


novell.com/inner 


<HTML> Reply | <HTML> 
<a href="../inner/prices/pricelist.html" class="ulink"> <a href="../prices/pricelist.html" class="ulink"> 


</HTML> </HTML> 


HTML Page: Source HTML Page: Source 


To make sure all the paths generated by JavaScript are rewritten, you must search the web pages of 
the application. You can then either list all the JavaScript methods and variables in the Additional 
Names to Search for URL Strings to Rewrite with Host Name section of the rewriter profile, or you 
can use the $path token in the Additional Strings to Replace section. The $path token reduces the 
number of JavaScript methods and variables that you otherwise need to list individually. 


To use the $path token, you add a search string and a replace string that uses the token. For 
example, if the /prices/pricelist.html page is generated by JavaScript and the multi-homing 
path for the proxy service is /inner, you would specify the following stings: 


Search String Replacement String 


/prices $path/prices 


This configuration allows the following paths to be rewritten before the web server sends the 
information to the browser. 
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Web Server String Rewritten String for the Browser 


/prices/pricelist .html /inner/prices/pricelist .html 


/prices /inner/prices 


This token can cause strings that shouldn’t be changed to be rewritten. If you enable the Rewrite 
Inbound Query String Data, Rewrite Inbound Post Data, and Rewrite Inbound Header actions, the 
rewriter checks these strings and ensures that they contain the information the web server expects. 
For example, when these options are enabled, the following paths and domain names are rewritten 
when found in query strings, in Post Data, or in the Call-Back, Destination, If, Notification-Type, or 
Referer headers. 


Browser String Rewritten String for the Web Server 
/inner/prices/pricelist.html /prices/pricelist.html 
/inner/prices /prices 
novell.com/inner/prices inner .com/prices 


3.8.5.4 Configuring the HTML Rewriter and Profile 


You configure the HTML rewriter for a proxy service, and these values are applied to all web servers 
that are protected by this proxy service. 


To configure the HTML rewriter: 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> HTML Rewriting. 


The HTML Rewriting page specifies which DNS names are to be rewritten. The HTML Rewriter 
Profile specifies which pages to search for DNS names that need to be rewritten. 


2 Select Enable HTML Rewriting. 


This option is enabled by default. When it is disabled, no rewriting occurs.When enabled, this 
option activates the internal HTML rewriter. This rewriter replaces the name of the web server 
with the published DNS name when sending data to the browsers. It replaces the published DNS 
name with the Web Server Host Name when sending data to the web server. It also makes sure 
the proper scheme (HTTP or HTTPS) is included in the URL. This is needed because you can 
configure Access Gateway to use HTTPS between itself and client browsers and to use HTTP 
between itself and the web servers. 


3 In the Additional DNS Name List section, click New, specify a DNS that appears on the web 
pages of your server (for example a DNS name other than the web server’s DNS name), then 
click OK. 


For more information, see “Determining Whether You Need to Specify Additional DNS Names” 
on page 142. 


4 In the Exclude DNS Name List section, click New, specify a DNS name that appears on the web 
pages of your server that you do not want rewritten, then click OK. 


For more information, see “Determining Whether You Need to Exclude DNS Names from Being 
Rewritten” on page 143. 
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Use the HTML Rewriter Profile List to configure a profile. Select one of the following actions: 


+ New: To create a profile, click New. Specify a display name for the profile and select either a 
Word or Character for the Search Boundary. Continue with “Creating or Modifying a 
Rewriter Profile” on page 153. 


+ Word: A Word profile searches for matches on words. For example, “get” matches the 
word “get” and any word that begins with “get” such as “getaway” but it does not match 
the “get” in “together” or “beget.” 


If you create multiple Word profiles, order is important. The first Word profile that 
matches the page is applied. Word profiles lower in the list are ignored. 


¢ Character: A Character profile searches for matches on a specified set of characters. 
For example, “top” matches the word “top” and the “top” in “tabletop,” “stopwatch,” and 
“topic.” 


If you want to add functionality to the default profile, create a Character profile. It has 
all the functionality of a Word profile, except searching for attribute names and Java 
variables and methods. If you create multiple Character profiles, order is important. 
The first Character profile that matches the page is applied. Character profiles lower in 
the list are ignored. 


+ Delete: To delete a profile, select the profile, then click Delete. 
+ Enable: To enable a profile, select the profile, then click Enable. 
+ Disable: To disable a profile, select the profile, then click Disable. 


¢ Modify: To view or modify the current configuration for a profile, click the name of the 
profile. Continue with “Creating or Modifying a Rewriter Profile” on page 153. 


The default profile is designed to be applied to all pages protected by Access Gateway. It is 
not specific to a reverse proxy or its proxy services. If you modify its behavior, remember its 
scope. Rather than modify the default profile, you must create your own custom Word 
profile and enable it. 


If you have more than one profile in the HTML Rewriter Profile List, use the up-arrow and down- 
arrow buttons to order the profiles. 


If you create more than one profile, order becomes important. For example if you want to rewrite 
all pages with a general rewriter profile (with a URL such as /*) and one specific set of pages 
with another rewriter profile (with a URL such as /doc/100506/*), you need to have the specific 
rewriter profile listed before the general rewriter profile. 


Even if multiple Word or Character profiles are enabled, a maximum of one Word profile and one 
Character profile is executed per page. The first Word profile and Character profile in the list that 
matches a page are executed, and the others are ignored. 


Enable the profiles you want to use for this protected resource. Select the profile, then click 
Enable. 


The default profile cannot be disabled. However, it is not executed if you have enabled another 
Word profile that matches your pages, and this profile comes before the default profile in the 
list. 


8 To save your changes to browser cache, click OK. 


9 To apply your changes, click the Access Gateways link, then click Update > OK. 


10 


The cached pages affected by the rewriter changes must be updated on Access Gateway. Do 
one of the following: 


+ If the changes affect numerous pages, click Access Gateways, select the name of the 
server, then click Actions > Purge All Cache. 


+ Ifthe changes affect only a few pages, you can refresh or reload the pages within the 
browser. 
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3.8.5.5 Creating or Modifying a Rewriter Profile 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> HTML Rewriting. 


2 Select one of the following: 
+ To create a new profile, click New, specify a name, select a profile type, then click OK. 
+ To modify a profile, click the name of the profile. 


3 Use the Requested URLs to Search section to set up a policy for specifying the URLs you want 
this profile to match. 


Fill in the following fields: 


If Requested URL Is: Specify the URLs of the pages you want this profile to match. Click New to 
add a URL to the text box. To add multiple values, enter each value on a separate line. 


And Requested URL Is Not: Specify the URLs of pages that this profile must not match. Ifa 
page matches the URL in both the If Requested URL Is list and And Requested URL Is Not list, 
the profile does not match the page. Click New to add a URL to the text box. To add multiple 
values, enter each value on a separate line. 


And Document Content-Type Is: Select the content-types you want this profile to match. To 
add a new content-type, click New and specify the name such as text/dns. Search your web 
pages for content-types to determine if you need to add new types. To add multiple values, enter 
each value on a separate line. 


For more information about how to use these options, see “Page Matching Criteria for Rewriter 
Profiles” on page 145. 


4 Use the Actions section to specify the actions the rewriter must perform if the page matches the 
criteria in the Requested URLs to Search section. 


Configure the following actions: 


Rewrite Inbound Query String Data: (Not available for Character profiles) Select this option to 
rewrite the domain and URL in the query string to match the web server. To use this option, your 
proxy service must meet the conditions listed in “Possible Actions for Rewriter Profiles” on 

page 146. 


Rewrite Inbound Post Data: (Not available for Character profiles) Select this option to rewrite 
the domain and URL in the Post Data to match the web server. To use this option, your proxy 
service must meet the conditions listed in “Possible Actions for Rewriter Profiles” on page 146. 


Rewrite Inbound Headers: Select this option to rewrite the following headers: 


Call-Back 

Destination 

If 

Notification-Type 

Referer 

Enable Rewriter Actions: Select this action to enable the rewriter to perform any actions: 


¢ Select it to have the rewriter use the profile to rewrite references and data on the page. If 
this option is not selected, you cannot configure the action options. 


+ Leave it unselected to disable rewriting. This allows you to create a profile for the pages you 
do not want rewritten. 


5 (Not available for Character profiles) If your pages contain JavaScript, use the Additional Names 
to Search for URL Strings to Rewrite with Host Name section to specify JavaScript variables or 
methods. You can also add HTML attribute names. (For the list of attribute names that are 
automatically searched, see “HTML Tags” on page 141.) 
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Fill in the following fields: 


Variable or Attribute Name to Search for Is: Lists the name of an HTML attribute or 
JavaScript variable to search to see if its value contains a URL string. Click New to add a name 
to the text box. To add multiple values, enter each value on a separate line. 


JavaScript Method to Search for Is: Lists the names of Java methods to search to see if their 
parameters contain a URL string. Click New to add a method to the text box. To add multiple 
values, enter each value on a separate line. 


Use the Additional Strings to Replace section to specify a string to search for and specify the 
text it must be replaced with. The search boundary (word or character) that you specified when 
creating the profile is used when searching for the string. 


To add a string, click New, then fill in the following: 


Search: Specify the string you want to search for. The profile type controls the matching and 
replacement rules. For more information, see one of the following: 


¢ “String Replacement Rules for Character Profiles” on page 149 

¢ “String Replacement Rules for Word Profiles” on page 148 

+ “Using $path to Rewrite Paths in JavaScript Methods or Variables” on page 150 
Replace With: Specify the string you want to use in place of the search string. 


7 Click OK. 
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+ 
+ 


+ 


If you have more than one profile in the HTML Rewriter Profile List, use the up-arrow and down- 
arrow buttons to order the profiles. 


If you create more than one profile, order becomes important. For example if you want to rewrite 
all pages with a general rewriter profile (with a URL such as /*) and one specific set of pages with 
another rewriter profile (with a URL such as /doc/100506/*), you need to have the specific 
rewriter profile listed before the general rewriter profile. 


Even if multiple Word or Character profiles are enabled, a maximum of one Word profile and one 
Character profile is executed per page. The first Word profile and Character profile in the list that 
matches a page are executed, and the others are ignored. 


Enable the profiles you want to use for this protected resource. Select the profile, then click 
Enable. 


The default profile cannot be disabled. However, it is not executed if you have enabled another 
Word profile that matches your pages, and this profile comes before the default profile in the list. 


To save your changes to browser cache, click OK. 
To apply your changes, click the Access Gateways link, then click Update > OK. 


The cached pages affected by the rewriter changes must be updated on Access Gateway. Do 
one of the following: 


+ Ifthe changes affect numerous pages, click Access Gateways, select the name of the 
server, then click Actions > Purge All Cache. 


+ Ifthe changes affect only a few pages, refresh or reload the page within the browser. 


Disabling the Rewriter 


There are three methods you can use to disable the internal rewriter: 


“Disabling per Proxy Service” on page 155 
“Disabling per URL” on page 155 
“Disabling with Page Modifications” on page 155 
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Disabling per Proxy Service 


By default, the rewriter is enabled for all proxy services. The rewriter can slow performance because 
of the parsing overhead. In some cases, a website might not have content with URL references that 
need to be rewritten. The rewriter can be disabled on the proxy service that protects that website. 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> HTML Rewriting. 

2 Deselect the Enable HTML Rewriting option, then click OK. 

3 To apply your changes, click the Access Gateways link, then click Update > OK. 

4 Select Access Gateway, then click Actions > Purge All Cache > OK. 


Disabling per URL 


You can also specify a list of URLs that are to be excluded from being rewritten for the selected proxy 
service. 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> HTML Rewriting. 
2 Click the name of the Word profile defined for this proxy service. 


If you have not defined a custom Word profile for the proxy service, you might want to create 
one. If you modify the default profile, those changes are applied to all proxy services. 


3 In the And Requested URL Is Not section, click New, then specify the names of the URLs you do 
not want rewritten. 


Specify each URL on a separate line. 
4 Click OK twice. 


5 Inthe HTML Rewriter Profile List, make sure the profile you have modified is enabled and at the 
top of the list, then click OK. 


6 To apply your changes, click the Access Gateways link, then click Update > OK. 
7 Select Access Gateway, then click Actions > Purge All Cache > OK. 


Disabling with Page Modifications 


There are cases when the URLs in only part of a page or in some of the JavaScript or form can be 
rewritten and the rest must not be rewritten. When this is the case, you might need to modify the 
content on the web server. Although this deviates from the design behind Access Manager, you might 
encounter circumstances where it cannot be avoided. 


You can add the following types of tags to the pages on the web server: 
+ Page Tags 
+ Param Tags 
+ Form Tags 


These tags are seen by browsers as a comment mark, and do not show up on the screen (except 
possibly on older browser versions). 


NOTE: If the pages you modify are cached on Access Gateway, you need to purge the cache before 
the changes become effective. Click Access Gateways, select the name of the server, then click 
Actions > Purge All Cache 


Page Tags: If you want only portions of a page rewritten, you can add the following tags to the page. 
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<!--NOVELL_REWRITER_OFF- -> 
HTML data not to be rewritten 


<!--NOVELL_REWRITER_ON- -> 


The last tag is optional, and if omitted, it prevents the rest of the page from being rewritten after the 
<!--NOVELL_REWRITER_OFF- -> tag is encountered. 


Param Tags: Sometimes the JavaScript on the page contains <param> elements that contain a value 
attribute with a URL. You can enable global rewriting of this attribute by adding value to the list of 
variable and attribute names to search for. If you need more control because some URLs need to be 
rewritten but others cannot be rewritten, you can turn on and turn off the value rewriting by adding 
the following tags before and after the <param> element in the JavaScript. 


<!--NOVELL_REWRITE_ATTRIBUTE_ON='value' - -> 
<param> elements to be rewritten 
<!--NOVELL_REWRITE_ATTRIBUTE_OFF='value' - -> 


<param> elements that shouldn't be rewritten 


Form Tags: Some applications have forms in which the <input>, <button>, and <option> elements 
contain a value attribute with a URL. You can enable global rewriting of these attributes by adding 
formvalue to the list of variable and attribute names to search for. If you need more control because 
some URLs need to be rewritten but others cannot be rewritten, you can turn on and turn off the 
formvalue rewriting by adding the following tags before and after the <input>, <button>, and 
<option> elements in the form. 


<!--NOVELL_REWRITE_ATTRIBUTE_ON=' formvalue' - -> 
<input>, <button>, and <option> elements to be rewritten 
<!--NOVELL_REWRITE_ATTRIBUTE_OFF=' formvalue' - -> 


<input>, <button>, and <option> elements that shouldn't be rewritten 


Configuring Connection and Session Limits 


Access Gateway establishes connections with clients and with web servers. For most networks, the 
default values for unresponsive connections and sessions provide adequate performance, but you 
can fine-tune the options for your network, its performance requirements, and your users: 

¢ Section 3.8.6.1, “Configuring TCP Listen Options for Clients,” on page 157 

¢ Section 3.8.6.2, “Configuring TCP Connect Options for Web Servers,” on page 158 

¢ Section 3.8.6.3, “Configuring Connection and Session Persistence,” on page 159 

¢ Section 3.8.6.4, “Configuring Web Servers,” on page 159 
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3.8.6.1 


Authentication time limits for inactivity sessions are configured on the contract and enforced by 
Identity Server. For information about how to configure this limit, see “Assigning a Timeout Per 
Protected Resource” on page 136. 


Configuring TCP Listen Options for Clients 


The TCP listen options allow you to control how idle and unresponsive browser connections are 
handled and to optimize these processes for your network. For most networks, the default values 
provide adequate performance. If your network is congested and slow, you might want to increase 
some of the limits. 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > TCP Listen Options. 


2 Select Enable Persistent Connections to allow Access Gateway to establish a persistent HTTP 
connection between Access Gateway and the browser. Usually, HTTP connections service only 
one request and response sequence. A persistent connection allows multiple requests to be 
serviced before the connection is closed. 


This option is enabled by default. 
3 Specify values for the TCP Listen Options: 


Keep Alive Interval: Determines when an idle connection is closed. If no application data is 
exchanged over a connection for this amount of time, the connection is closed. This value limits 
how long an idle persistent connection is kept open. This setting is a compromise between 
freeing resources to allow additional inbound connections, and keeping connections established 
so that new connections from the same device do not need to be re-established. The value can 
be set from 1 to 1440 seconds (24 minutes). The default is 300 seconds (5 minutes). 


Data Read Timeout: Determines when an unresponsive connection is closed. When 
exchanging data, if an expected response from the connected device is not received within this 
amount of time, the connection is closed. This value might need to be increased for slow or 
congested network links. The value can be set from 1 to 3600 seconds (1 hour). The default is 
120 seconds (2 minutes). 


4 To configure the encryption key, select one or more of the following: 


Enforce 128-Bit Encryption between Browser and Access Gateway: When this option is 
selected, Access Gateway requires all its server connections with client browsers to use 128-bit 
encryption. If the encryption key is less than 128, regardless of the cipher suite, the connection is 
denied. 


Enforce 128-Bit Encryption between Access Gateway and Web Server: When this option is 
selected, Access Gateway requires all its client connections to web servers to use 128-bit 
encryption. If the encryption key is less than 128, regardless of the cipher suite, the connection is 
denied. 


NOTE: These SSL listening options appear disabled if you are configuring the tunneling 
services. 


5 To save your changes to browser cache, click OK. 
6 To apply your changes, click the Access Gateways link, then click Update > OK. 
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Configuring TCP Connect Options for Web Servers 


Connect options are specific to the group of web servers configured for a proxy service. They allow 
you to control how idle and unresponsive web server connections are handled and to optimize these 
processes for your network. For most networks, the default values provide adequate performance. If 
your network is congested and slow, you might want to increase some of the limits. 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 


> Web Servers > TCP Connect Options. 
Configure the IP address to use when establishing connections with web servers: 


Cluster Member: (Available only if Access Gateway is a member of a cluster.) Select the server 
you want to configure from the list of servers. Only the value of the Make Outbound Connection 
Using option applies to the selected server. 


Make Outbound Connection Using: (Access Gateway Appliance) Specifies which IP address 
the proxy service must use when establishing connections with the back-end web servers. 


Select how the web servers must be contacted when multiple web servers are available. Select 
one of the following for the Policy for Multiple Destination IP Addresses option: 


¢ Simple Failover: Allows the next available web server in the group to be contacted when 
the first server in the list is no longer available. 


¢ Round Robin: Moves in order through the list of web servers, allowing each to service 
requests before starting at the beginning of the list for a second group of requests. 


NOTE: The Make Outbound Connection Using and Policy for Multiple Destination IP 
Addresses options are available in Access Gateway Appliance and the same options are not 
available in Access Gateway Services. 


Select Enable Persistent Connections to allow Access Gateway to establish a persistent HTTP 
connection between Access Gateway and the web server. Usually, HTTP connections service 
only one request and response sequence. A persistent connection allows multiple requests to be 
serviced before the connection is closed. 


This option is enabled by default. 


To modify the connection timeouts between Access Gateway and the web servers, configure the 
following fields: 


Data Read Timeout: Determines when an unresponsive connection is closed. When 
exchanging data, if an expected response from the connected device is not received within this 
amount of time, the connection is closed. This value might need to be increased for slow or 
congested network links. The value can be set from 1 to 3600 seconds (1 hour). The default is 
120 seconds (2 minutes). 


Idle Timeout: Determines when an idle connection is closed. If no application data is exchanged 
over a connection for this amount of time, the connection is closed. This value limits how long an 
idle persistent connection is kept open. This setting is a compromise between freeing resources 
to allow additional inbound connections, and keeping connections established so that new 
connections from the same device do not need to be re-established. The value can be set from 1 
to 1800 seconds (30 minutes). The default is 180 seconds (3 minutes). 


6 To save your changes to browser cache, click OK. 
7 To apply your changes, click the Access Gateways link, then click Update > OK. 
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3.8.6.3 


3.8.6.4 


Configuring Connection and Session Persistence 


Access Gateway establishes three types of connections: 


+ Access Gateway to browser 
e Access Gateway to web server 
+ Browser to web server 


Access Gateway connections to the browser and Access Gateway connections to the web server 
involve setting up a TCP connection for an HTTP request. HTTP connections usually service only 
one request and response sequence, and the TCP connection is opened and closed during the 
sequence. A persistent connection allows multiple requests to be serviced before the connection is 
closed and saves a significant amount of processing time. To configure this type of persistence, see 
the following: 


+ Access Gateway to Browser: Click Devices > Access Gateways > Edit > [Name of Reverse 
Proxy] > TCP Listen Options and configure the Enable Persistent Connections option. 


+ Access Gateway to Web Server: Click Devices > Access Gateways > Edit > [Name of 
Reverse Proxy] > [Name of Proxy Service] > Web Servers > TCP Connect Options and 
configure the Enable Persistent Connections option. 


The persistence of the browser to web server connection is always enabled and is not configurable. 
This feature allows a browser to use the same web server after an initial connection has been 
established. Most web applications are designed to expect this type of behavior. 


Configuring Web Servers 


The web server configuration determines how Access Gateway handles connections and packets 
between itself and the web servers. For more information about web Server configuration, see 
Section 3.8.3, “Configuring Web Servers of a Proxy Service,” on page 126 


1 Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Web 
Servers. 


2 The session stickiness provides information about the web server session connection details. 


Enable Session Stickiness: Default the Session Stickiness check box is enabled and this 
option makes the proxy server to use the same web server for all fills during a session. 


3 If your browsers are capable of sending HTTP 1.1 requests, configure the following field to 
match your web servers: 


Enable Force HTTP 1.0 to Origin: Indicates whether HTTP 1.1 requests from browsers are 
translated to HTTP 1.0 requests before sending them to the web server. If your browsers are 
sending HTTP 1.1 requests and your web server can only handle HTTP 1.0 requests, you must 
enable this option. 


When the option is enabled, Access Gateway translates an HTTP 1.1 request to an HTTP 1.0 
request. 


4 To enable SSL connections between the proxy service and its web servers, select Connect 
Using SSL. For configuration information for this option, Web Server Trusted Root, and SSL 
Mutual Certificate, see Section 17.6, “Configuring SSL between the Proxy Service and the Web 
Servers,” on page 995. 


5 In the Connect Port field, specify the port that Access Gateway must use to communicate with 
the web servers. The following table lists some default port values for common types of web 
servers. 
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Server Type Non-Secure Port Secure Port 


Web server with HTML content 80 443 
WebSphere 9080 9443 
JBoss 8080 8443 


To control how idle and unresponsive web server connections are handled and to optimize these 
processes for your network, select TCP Connect Options. For more information, see 
“Configuring TCP Connect Options for Web Servers” on page 158. 


To add a web server, click New in the Web Server List and specify the IP address or the fully 
qualified DNS name of the web server. 


The web servers added to this list must contain identical web content. Configuring your system 
with multiple servers with the same content adds fault tolerance and increases the speed for 
processing requests. For more information about this process, see “Setting Up a Group of Web 
Servers” on page 169. 


+ New: To create a new web server, click New. Specify the web Server IP Address or DNS. 
Click OK to add the new web server to the list or Cancel to discard the changes. 


After creating the web server in the list, you can configure it as primary server and prioritize 
the list of web servers based on your requirement. 


+ Delete: To delete a web server, select the web server from the list, then click Delete. 


If you delete the selected web server, then all the web servers which are corresponding to 
the device in the cluster gets deleted. 


In case of Simple failover policy, the web server list will be ordered allowing selection of the 
primary web server. 


The most common use case is, same list of web servers as well as primary designate, in all the 
Gateway Appliances in a cluster. However, there can be scenarios where you want Gateway 
Appliances in a cluster to have different configuration for the above, one of them being locations 
separated geographically, each hosting Gateway Appliances, as well as some of the web 
servers. For such cases, select the individual members from the Cluster/Cluster Member drop 
down list, and configure the primary as well as other web servers for each 


NOTE: When the administrator opts for member change then the administrator cannot change 
the priority of web servers from the cluster but the other operations such as add, delete can be 
performed. 


Primary Web Server: The web server which serves all the requests for this service. Only 
applicable for simple failover. 


Group Web Servers: The web servers which are added at the cluster level will be common and 
displayed in all cluster member groups. 


For more information about this process, see “Configuring Web Servers at Cluster Level” on 
page 170 and “Configuring Web Servers at Member Level” on page 171. 


9 To save your changes to browser cache, click OK. 
10 To apply your changes, click the Access Gateways link, then click Update > OK. 
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3.8.7 Protecting Multiple Resources 


Figure 3-14 Hierarchical View of Access Gateway Configured Objects 
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In Figure 3-14, Access Gateway 1 and Access Gateway 2 have the same configuration except for the 
reverse proxy listening address. They share the other configuration settings because they are 
members of an Access Gateway cluster. This section explains how to create a group of web servers, 
how to add multiple proxy services and reverse proxies to an Access Gateway, and how to manage a 
cluster of Access Gateways. 


3.8.7.1 | Using Multi-Homing to Access Multiple Resources 


You can configure an Access Gateway to use one public IP address to protect multiple types of web 
resources. This is one of the major benefits of Access Gateway, because it conserves valuable 
resources such as IP addresses. This feature also makes an Access Gateway a multi-homing device 
because it becomes a single endpoint supporting multiple back-end resources. 


You can select to use only one multi-homing method, or you can use multiple methods. Select the 
methods that meet the needs of your network and the resources you are protecting. The first proxy 
service configured for a reverse proxy is always configured to use the DNS name of Access Gateway. 
Subsequent proxy services can be configured to use one of the following methods: 


+ “Domain-Based Multi-Homing” on page 162 
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+ “Path-Based Multi-Homing” on page 163 
¢ “Virtual Multi-Homing” on page 166 


This section describes these multi-homing methods, then explains the following: 


¢ “Creating a Second Proxy Service” on page 167 
+ “Configuring a Path-Based Multi-Homing Proxy Service” on page 168 


Domain-Based Multi-Homing 


Domain-based multi-homing is based on the cookie domain. For example, if you have a cookie 
domain of company.com, you can prefix hostnames to a cookie domain name. For a test resource, 
you can prefix test to company.com and have test.company.com resolve to the IP address of 
Access Gateway. Access Gateway configuration for the test .company.com proxy service contains 
the information for accessing its web servers (test1.com). Figure 3-15 illustrates this type of 
configuration for three proxy services. 


Figure 3-15 Using a Base Domain Name with Host Names 


Firewall 


ya 


test1.com 
test2.com 
test3.com 
Access Gateway 
DNS Names: 

test.company.com 

sales.company.com 

apps.company.com sales4.com 
sales5.com 


IP Address: 
10.10.195.90:80 


OQO 


T 


apps6.com 
apps7.com 
apps8.com 


Domain-based multi-homing has the following characteristics: 
¢ If you are using SSL, the back-end servers can all listen on the same SSL port (the default for 
HTTPS is 443). 


¢ If you are using SSL, the back-end servers can share the same SSL certificate. Instead of using 
a specific hostname in the SSL certificate, the certificate can use a wildcard name such as 
* company.com, which matches all the servers. 
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Before configuring Access Gateway, you need to complete the following: 


+ Create the published DNS names with a common domain name for public access to the back- 
end resources. For example, the table below lists three DNS names that use company.com as a 
common domain name, lists the IP address that these DNS names resolve to, and the web 
servers they protect. 


Published DNS Name Access Gateway IP Web Server Host Name Web Server IP Address 


Address 
test.company.com 10.10.195.90:80 test.internal.com 10.10.15.10 
sales.company.com 10.10.195.90:80 sales.internal.com 10.10.15.20 
apps.company.com 10.10.195.90:80 apps.internal.com 10.10.15.30 


+ Configure your DNS server to resolve the published DNS names to the IP address of Access 
Gateway. 


+ Set up the back-end web servers. 
¢ Create three proxy services for these published DNS names. 


To create a domain-based multi-homing proxy service, see “Creating a Second Proxy Service” 
on page 167, and select domain-based for the multi-homing type. 


Path-Based Multi-Homing 


Path-based multi-homing uses the same DNS name for all resources, but each resource or resource 
group must have a unique path appended to the DNS name. For example, if the DNS name is 
test.com, you would append /sales to test.com. When the user enters the URL of www. test .com/ 
sales, Access Gateway resolves the URL to the sales resource group. Figure 3-16 illustrates this 
type of configuration. 
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Figure 3-16 Using a Domain Name with Path Elements 
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Path-based multi-homing has the following characteristics: 
+ Itis considered to be more secure than domain-based multi-homing, because some security 
experts consider wildcard certificates less secure than a certificate with a specific hostname. 
+ Each resource or group of resources must have a unique starting path. 


¢ JavaScript applications might not work as designed if they obscure the URL path. Access 
Gateway needs access to the URL path, and if it is obscured, the path cannot be resolved to the 
correct back-end resource. 


+ The protected resources for each path-based child come from the parent proxy service. 
The following sections explain how to configure path-based proxy services and your network so that 
Access Gateway can find the correct protected resources: 

¢ Configuring the Remove the Path on Fill Option 

¢ Configuring the Host Header Option 

¢ Configuring the Host Header Option 

¢ Preparing for Path-Based Multi-Homing 


Configuring the Remove the Path on Fill Option 


If the path that is part of the published DNS name (/sales or /apps) is used to identify a resource but 
is not part of directory configuration on the web server, the path needs to be removed from the URL 
before the request is sent to the web server. For example, suppose you use the following 
configuration: 
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Browser URL Using the Published DNS Name Web Server URL 


http://www.test.com/sales http://sales4.internal.com/ 


In this case, the path needs to be removed from the URL that Access Gateway sends to the web 
server. Access Gateway does not allow you to set up multiple paths to this type of web server, so all 
pages must have the same authentication requirements. 


If the path in the published DNS name is a path on the web server, the path needs to be passed to the 
web server as part of the URL. For example, suppose you use the following configuration: 


Browser URL Using the Published DNS Name Web Server URL 


http://www.test.com/sales http://sales4.internal.com/sales 


Because the path component specifies a directory on the web server where the content begins, you 
need to select to include the path. Access Gateway then includes the path as part of the URL it sends 
to the web server. This configuration allows you to set up multiple paths to the web server, such as 


¢ sales/payroll 
+ sales/reports 
+ sales/products 


Such a configuration also allows you to set up different authentication and authorization requirements 
for each path. 


Configuring the Host Header Option 


When you create path-based proxy services and also enable the Remove Path on Fill option, you 
need to know what types of links exist on the web servers. For example, you need to know if the sales 
web servers in Figure 3-16 on page 164 have links to the app web servers or to the test web servers. 
If they don’t, you can set the Host Header option to either Forward Received Host Name or to Web 
Server Host Name. However, if they do contain links to each other, you need to set the Host Header 
option to Web Server Host Name and specify a DNS name for the web server in the Web Server Host 
Name option. Access Gateway needs a method to distinguish between the web servers other than 
the path, because after the path is removed, all the web servers in Figure 3-16 on page 164 have the 
same name: www.test.com. 


If you select to use the Forward Received Host Name option for a path-based service, you might also 
need to add entries to the Additional DNS Name List for the rewriter. For more information, see 
“Determining Whether You Need to Specify Additional DNS Names” on page 142. 


Preparing for Path-Based Multi-Homing 
Before configuring Access Gateway, you need to complete the following: 


+ Create the published DNS names with paths for public access to the back-end resources. For 
example, the table below uses test .com as the domain name. It lists three published DNS 
names (two with paths), the IP address these names resolve to, and the web servers that they 
are going to protect: 
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Published DNS Name Access Gateway Web Server Host Web Server IP 


IP Address Name Address 
test.com 10.10.195.90:80 test.internal.com 10.10.15.10 
test.com/sales 10.10.195.90:80 sales.internal.com 10.10.15.20 
test.com/apps 10.10.195.90:80 apps.internal.com 10.10.15.30 


+ Configure your DNS server to resolve the published DNS names to the IP address of Access 
Gateway. 


+ Setup the back-end web servers. If they have links to each other, set up DNS names for the web 
servers. 


+ Create one proxy service that uses test .comas its published DNS name and two path-based 
proxy services. 


To create a path-based multi-homing proxy service, see “Creating a Second Proxy Service” on 
page 167, and select path-based for the multi-homing type. 


Virtual Multi-Homing 
Virtual multi-homing allows you to use DNS names from different domains (for example test .com 


and sales.com). Each of these domain names must resolve to Access Gateway host. Figure 3-17 
illustrates this type of configuration. 


Figure 3-17 Using Multiple DNS Names 
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Virtual multi-homing cannot be used with SSL. You must use this configuration with resources that 
need to be protected, but the information exchanged must be public information that does not need to 
be secure. For example, you could use this configuration to protect your web servers that contain the 
catalog of your shipping products. It isn’t until the user selects to order a product that you need to 
switch the user to a secure site. 


Whether a client can use one DNS name or multiple DNS names to access Access Gateway 
depends upon the configuration of your DNS server. After you have configured your DNS server to 
allow multiple names to resolve to the same IP address, you are ready to configure Access Gateway. 


To create a virtual multi-homing proxy service, see “Creating a Second Proxy Service” on page 167, 
and select Virtual for the multi-homing type. 


Creating a Second Proxy Service 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 
2 In the Proxy Service List, select New. 
3 Fill in the fields. 


Proxy Service Name: Specify a display name for the proxy service. For the sales group, you 
might use sales. For the group of application servers, you might use apps. 


Multi-Homing Type: Specify the multi-homing method that Access Gateway must use to identify 
this proxy service. Select one of the following: 


+ Domain-Based: Uses the published DNS name (www. test .com) with a hostname 
(www.newsite.test.com). For more information, see “Domain-Based Multi-Homing’” on 
page 162. 


+ Path-Based: Uses the published DNS name (www. test .com) with a path (www. test .com/ 
path). For more information, see “Path-Based Multi-Homing” on page 163. 


+ Virtual: Uses a unique DNS name (www. newsite.newcompany.com). Virtual multi-homing 
cannot be used with SSL. For more information, see “Virtual Multi-Homing” on page 166. If 
you need a unique DNS name and SSL, you need to create a reverse proxy rather than a 
proxy service. For information about creating a second reverse proxy, see “Managing 
Multiple Reverse Proxies” on page 172. 


Published DNS Name: Specify the DNS name you want the public to use to access your site. 
This DNS name must resolve to the IP address you set up as the listening address. This option 
is not available when path-based multi-homing is selected. 


Path: Specify the path to use for this proxy service. This option is available only when path- 
based multi-homing is selected. 


Web Server IP Address: Specify the IP address of the web server you want this proxy service 
to manage. 


Host Header: Specify whether the HTTP header must contain the name of the back-end web 
server (Web Server Host Name option) or whether the HTTP header must contain the published 
DNS name (the Forward Received Host Name option). 


For a path-based multi-homing service, it is usually best to select the Web Server Host Name 
option. For more information, see “Configuring the Host Header Option” on page 165. 


Web Server Host Name: Specify the DNS name of the web server that Access Gateway must 
forward to the web server. If you have set up a DNS name for the web server and the web server 
requires its DNS name in the HTTP header, specify that name in this field. If you selected 
Forward Received Host Name, this option is not available. 


For iChain administrators, the Web Server Host Name is the alternate hostname when 
configuring a Web Server Accelerator. 
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4 Click OK. 
5 To continue, select one of the following: 


¢ To configure a virtual or domain-based proxy service, see “Configuring a Proxy Service” on 
page 122. 


¢ To configure a path-based proxy service, see “Configuring a Path-Based Multi-Homing 
Proxy Service” on page 168. 


Configuring a Path-Based Multi-Homing Proxy Service 
To configure a path-based proxy service: 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Path-Based 


Multi-Homing Proxy Service]. 


The following fields display information that must be configured on the parent proxy service (the 
first proxy service created for this reverse proxy). 


Published DNS Name: Displays the value that users are currently using to access this proxy 
service. This DNS name must resolve to the IP address you set up as a listening address on 
Access Gateway. 


Cookie Domain: Displays the domain for which the cookie is valid. The web server that the user 
is accessing must be configured to be part of this domain. 


Configure the following options: 


Description: (Optional) Provide a description of the purpose of this proxy service or specify any 
other pertinent information. 


HTTP Options: Determines how the proxy service handles HTTP headers and caching. For 
more information, see Section 4.3.2, “Controlling Browser Caching,” on page 333. 


Advanced Options: (Access Gateway Service) See Section 4.4.2, “Configuring Advanced 
Options for Domain-Based and Path-Based Multi-Homing Proxy Services,” on page 346. 


Configure the path options: 


Remove Path on Fill: Determines whether the multi-homing path is removed from the URL 
before forwarding it to the web server. If the path is not a directory at the root of the web server, 
the path must be removed. If this option is selected, the path is stripped from the request before 
the request is sent to the web server. 


If you enable this option, this proxy service can protect only one path. If you have configured 
multiple paths in the Path List, you cannot enable this option until you have deleted all but one 
path. 


Reinsert Path in “set-cookie” Header: Determines whether the path is inserted into the Set- 
Cookie header. This option is only available if you enable the Remove Path on Fill option. 


Determine whether you need to create a protected resource for your path. 


In the Path List, the path you specified is listed along with the protected resource that best 
matches its path. 


Access Gateway automatically selects the protected resource that is used with the specified 
path. It selects the current protected resource whose URL path most closely matches the 
specified path. 


+ If you have a protected resource with a URL path of /*, Access Gateway selects that 
resource unless you have configured a protected resource that has a URL path that more 
closely matches the path specified on this page. 
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4b 


4c 


4d 
4e 
4f 
4g 


4h 
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4j 


If you add a protected resource at a future time and its URL path more closely matches the 
path specified on this page, Access Gateway automatically reconfigures to use this new 
protected resource. 


If you disable a protected resource that Access Gateway has assigned to a path-based 
service, Access Gateway automatically reconfigures and selects the next protected 
resource that most closely matches the path specified on this page. 


In the Path List section, click the Protected Resource link. 


Examine the contract, Authorization, Identity Injection, and Form Fill policies assigned to 
this protected resource to ensure that they meet the requirements for your path-based 
service. 


To return to the Path-Based Multi-Homing page, click the Overview tab, then click OK. 
+ Ifthe protected resource meets your needs, continue with Step 5 


+ If the protected resource does not meet your needs, you must create a protected 
resource for the path-based proxy service. Continue with Step 4d. 


Click OK, select the name of the parent proxy service, then click Protected Resources. 
In the Protected Resource List, click New, specify a name, then click OK. 
Select an Authentication Procedure. 


In the URL Path List, specify the path you used when creating the path-based proxy 
service. For example, if your path was /apps, specify /apps/* or /apps in the URL Path 
List. 


IMPORTANT: If you create multiple protected resources that exactly match the path-based 
multi-homing service, there is no guarantee that a specific protected resource will be used. 
For example, if you create protected resources for both of the paths specified above (/apps 
and /apps/*) and you have a path-based service with a path of /apps, either of these 
protected resources could be assigned to this path-based service in Administration Console 
or used when access is requested. 


Make sure the protected resource you created is enabled. If the resource is disabled, it 
does not appear in the Path List for the path-based proxy service. 


(Optional) Enable the policies the path-based proxy service requires. Click Authorization, 
Identity Injection, or Form Fill and enable the appropriate policies. 


Click OK. 


5 Click OK. 
6 To apply the changes, click the Access Gateways link, then click Update > OK. 


Setting Up a Group of Web Servers 


You can configure a proxy service to service a “virtual” group of web servers, which adds load 
balancing and redundancy. Each web server in the group must contain the same material. When you 
create the proxy service, you set up the first server by specifying the URLs you want users to access 
and the rights the users need for each URL. When you add additional web servers to the proxy 
service, these servers automatically inherit everything you have configured for the first web server. 
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Figure 3-18 Adding Redundant Web Servers 
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For this configuration, you use a single reverse proxy and proxy service. To add multiple web servers 
to a host: 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> Web Servers. 
2 In the Web Server List section, click New. 


3 Specify the IP address or the fully qualified DNS name of another web server for the “virtual” 
group, then click OK. 


4 Repeat Step2 and Step3 to add additional web servers to the group. 
5 Click OK. 
6 To apply the changes, click the Access Gateways link, then click Update > OK. 


Access Gateway uses the round robin algorithm by default. You can configure it to use the simple 
failover algorithm. 


Simple failover sends all the traffic to the first web server as long as it is available. Traffic is sent to 
another web server in the list only when the first web server is no longer available. To configure this 
option, see “Configuring TCP Connect Options for Web Servers” on page 158. 


Connection persistence is enabled by default. This allows Access Gateway to send multiple HTTP 
requests to the web server to be serviced before the connection is closed. To configure this option, 
see “Configuring TCP Connect Options for Web Servers” on page 158. 


Session stickiness option is used if multiple web Servers are configured for a service. Selecting this 
option makes the proxy server to use the same web server for all fills during a session. This option is 
enabled by default. For more information about persistent connections, see “Configuring Connection 
and Session Persistence” on page 159. 


Configuring Web Servers at Cluster Level 


You can configure web servers at cluster level and view web servers at cluster level in the lag-cluster 
drop -down list. You can use this option when you want to create web servers at cluster level. 


Setting Up a Basic Access Manager Configuration 


TCP Connect Options 
Web Server configuration is cluster specific. 
Select the group device from the Cluster/Cluster Member drop-down to change the web server ordering. 


Cluster/Cluster Member: _ lag-cluster Y 


Web Server List 
New... | Delete 
C Web Server 
C] 172.16.1.95 Primary 4 


Cluster Member 


1 item(s) 


172.16.1.111 
172.16.1.112 
172.16.1.113 
172.16.1.114 


Server(s) must be updated bg his panel will be used. See Configuration Panel for summary of changes. 


OK Cancel 


You can sort the web servers in the cluster, add the web servers to the cluster, delete the web servers 
in the cluster and prioritize the web server list. 


lag-cluster 


1 Select the group device from the Cluster drop-down list to change the web server ordering. 
Click New to add a web server to the cluster or cluster member in the web server List. 

3 Specify the IP address or the fully qualified DNS name of the web server in the Web Server IP 
Address or DNS number. 


4 Click Delete to delete the web servers at the cluster/cluster member level. A message is 
displayed as “ If you delete web server from the cluster, then it will be deleted from all cluster 


members”. 
5 Click Ok to continue or Cancel to discard the changes. 


NOTE: If Access Gateway is configured to use Simple Failover, you can prioritize the web 
server list at the cluster level and this will reflect the changes in the all the cluster members list. 
When the web server is configured from cluster member, order cannot be changed from cluster 


because the order would be different from each cluster member. 


Configuring Web Servers at Member Level 


You can configure the web servers at the member level by adding and deleting the web servers. You 
can move up or down the web servers as primary web server. You can add a new web server at the 


cluster member level. 
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TCP Connect Options 
Web Server configuration is member specific. 
Select the individual device from the Cluster/Cluster Member drop-down to change the web server ordering. 


Cluster/Cluster Member: 172.16.1.113 ¥ 


Web Server List Cluster Member |X| 
New... | Delete 
C] Web Server 
[C] test Primary Server 


3 item(s) 


172.16.1.111 
172.16.1.112 


172.16.1.113 
172.16.1.95 Group Web 172.16.1.114 


(0 88 8! 


172.15.1.96 Group Web] lag-cluster 


Server(s) must be updated before changes made on this panel will be used. See Configuration Panel for summary of changes. 
_ 0K | Cancel | 


1 Click New and enter the Web Server IP Address or DNS number. A confirmation dialog displays 
the following message”. The web server addition makes this service's web server configuration 
as member specific. Henceforth the web server ordering must be changed from each cluster 
member”. 

2 Click OK to continue. 

3 Select the specific web server you ant to delete and click Delete. A message is displayed as 
"Delete the selected Web Server(s)?". Click OK to continue. 

4 If Access Gateway is configured to use Simple Failover, you can move up or down the web 
servers as primary web server. To configure Simple Failover, see “Configuring TCP Connect 
Options for Web Servers” on page 158. 


When the web server is deleted a message is displayed as "Web Server Address Changed. All 
cached content on this Server must be purged. Purge All Cache? " The system will purge the details 
of the deleted server. Using the arrow key you can configure the web servers as primary web server. 


NOTE: The primary web server at the member level is not the same at the cluster level. The web 
server list sorting will be different at both cluster and member level. 


Managing Multiple Reverse Proxies 


Each reverse proxy must have a unique IP address and port combination. If your Access Gateway 
has only one IP address, you must select unique port numbers for each additional reverse proxy that 
you create. You can configure Access Gateway to use multiple IP addresses. These addresses can 
be configured to use the same network interface card, or if you have installed multiple network cards, 
you can assign the IP addresses to different cards. 


+ Access Gateway Appliance: To configure IP addresses and network interface cards, see 
“Viewing and Modifying Adapter Settings” on page 319. 

e Access Gateway Service: You need to use system utilities to configure network interface cards 
and new IP addresses. After they are configured, you can use the New IP option to make them 
available for Gateway Service configuration. See “Adding a New IP Address to Access Gateway” 
on page 324. 

If you are creating more than one reverse proxy, you must select one to be used for authentication. 


By default, the first reverse proxy you create is assigned this task. Depending upon your Access 
Gateway configuration, you might want to set up one reverse proxy specifically for handling 
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authentication. The authentication reverse proxy is also used for logout. If you have web applications 
that contain logout options, these options need to be redirected to the Logout URL of the 
authentication proxy. 

+ “Managing Entries in the Reverse Proxy List” on page 173 

+ “Changing the Authentication Proxy Service” on page 173 


Managing Entries in the Reverse Proxy List 


1 Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication. 
2 In the Reverse Proxy List, select one of the following actions: 


+ New: To create a new reverse proxy, click New. You are prompted to enter a display name 
for the proxy. For configuration information, see Section 3.8.2, “Managing Reverse Proxies 
and Authentication,” on page 119. 


Reverse proxy names and proxy service names must be unique to Access Gateway. 
Protected resource names need to be unique to the proxy service, but they don’t need to be 
unique to Access Gateway. 


+ Delete: To delete a reverse proxy, select the check box next to a specific reverse proxy, 
then click Delete. To delete all reverse proxies, select the check box next to the Name 
column, then click Delete. 


+ Enable: To enable a reverse proxy, select the check box next to a specific reverse proxy, 
then click Enable. To enable all reverse proxies, select the check box next to the Name 
column, then click Enable. 


+ Disable: To disable a reverse proxy, select the check box next to a specific reverse proxy, 
then click Disable. To enable all reverse proxies, select the check box next to the Name 
column, then click Disable. 


3 Click OK. 
4 To apply the changes, click the Access Gateways link, then click Update > OK. 


Changing the Authentication Proxy Service 


If you have multiple reverse proxies, you can select the reverse proxy that users are redirected to for 
login and logout. 


IMPORTANT: Changing the reverse proxy that is used for authentication is not a trivial task. For 
example, if you have customized the logout options on your web servers to redirect the logout request 
to the Logout URL of the current authentication reverse proxy, you need to modify these options to 
point to a new Logout URL. 


If you have set up SSL connections, you need to change your certificate configurations. 


To select the reverse proxy to use for authentication: 


1 Click Devices > Access Gateways > Reverse Proxy / Authentication. 


2 In the Embedded Service Provider section, select a value for the Reverse Proxy option. This is 
the reverse proxy that is used for authentication. 


The screen is refreshed and the Metadata URL, Health-Check URL, and Logout URL are 
rewritten to use the selected reverse proxy. 
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(Conditional) If your Access Gateway certificates were generated by a different certificate 
authority than your Identity Server certificates, you need to import the trusted root of Identity 
Server into the trusted root keystore of the Embedded Service Provider. Click Auto-Import 
Identity Server Configuration Trusted Root, click OK, specify an alias, click OK, then click 
Close. 


If you don’t know whether you need to import the trusted root, click the option. If the trusted root 
is already in the keystore, the duplicate key is not imported and you are informed of this 
condition. 


In the Reverse Proxy List, click the name of the reverse proxy that you have selected for 
authentication. 


If you have enabled SSL between the Embedded Service Provider and Identity Server, you need 
to import the trusted root of the Embedded Service Provider into the trusted root keystore of 
Identity Server. Click Auto-Import Embedded Service Provider Trusted Root, click OK, specify 
an alias, click OK, then click Close. 


If you don’t know whether you need to import the trusted root, click the option. If the trusted root 
is already in the keystore, the duplicate key is not imported and you are informed of this 
condition. 


If you have enabled SSL between the browser and Access Gateway, you need to configure this 
reverse proxy for SSL. Use the Select Certificate icon to browse for the certificate that matches 
the DNS name of the proxy service or use the Auto-generate Key option to create a certificate 
that matches the DNS name of the proxy service. 


To save your changes to browser cache, click OK. 


8 To apply the changes, click the Access Gateways link, then click Update > OK. 


9 (Conditional) If you have customized web logout pages, update them to use the new Logout 


URL. 


3.9 Configuring Trusted Providers for Single Sign-On 


Access Manager provides the following information to configure single sign-on to different trusted 
providers. Access Manager also provides different ways to establish a SAML 2.0 connection to 
applications using connectors. Using connectors in simpler, but it works only for a specific set of 
SAML 2.0 applications. For more information, see “Understanding Federated Single Sign-On with 
SAML 2.0” in the Access Manager Applications Configuration Guide. 


This section discusses configuring trust so that two user accounts can be associated with each other 
without the sites exchanging user data. Topics include: 


+ 


+ 


+ 


+ 


+ 


Section 3.9.1, “Understanding the Trust Model,” on page 175 

Section 3.9.2, “Configuring General Provider Settings,” on page 177 

Section 3.9.3, “Managing Trusted Providers,” on page 181 

Section 3.9.4, “Modifying a Trusted Provider,” on page 185 

Section 3.9.5, “Communication Security,” on page 186 

Section 3.9.6, “Selecting Attributes for a Trusted Provider,” on page 187 

Section 3.9.7, “Managing Metadata,” on page 189 

Section 3.9.8, “Configuring an Authentication Response for a Service Provider,” on page 193 
Section 3.9.9, “Routing to an External Identity Provider Automatically,” on page 194 

Section 3.9.10, “Using the Intersite Transfer Service,” on page 194 
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3.9.1 


3.9.1.1 


Understanding the Trust Model 


Setting up trust involves system administrators agreeing on how to establish a secure method for 
providing and consuming authentication assertions between their Identity Servers. An Identity Server 
is always installed as an identity provider, which is used to provide authentication to trusted service 
providers and ESPs. It can also be configured to be a service provider and trust the authentication of 
an identity provider. 


¢ “Identity Providers and Consumers” on page 175 
+ “Embedded Service Providers” on page 176 


¢ “Configuration Overview” on page 176 


Identity Providers and Consumers 


An Identity Server can be configured as an identity provider, which allows other service providers to 
trust it for authentication. It can also be configured as a service provider, which enables Identity 
Server to consume authentication assertions from trusted identity providers. Figure 3-19 depicts two 
Identity Servers. Identity Server at the top of the figure is configured as an identity provider for SAML 
1.1, SAML 2.0, and Liberty authentication. Identity Server in the middle of the figure is configured as 
a service provider, consuming the authentication credentials of the top Identity Server. This second 
Identity Server is also configured as an identity provider, providing authentication for the Embedded 
Service Provider of Access Gateway. 


Figure 3-19 Identity Server Trust 


IDP 


identity Server Provides Authentication (SAML, SAML2, Liberty) 


SP (Consumes SAML, SAML2, and Liberty Authentication) 


Identity Server a IDP (Provides Authentication to ESP (Liberty Only) 


ESP 


Access Consumes Authentication (Liberty) 


Gateway 


As an administrator, you determine whether your server is to be used as the identity provider or 
service provider in the trust relationship. You and the trusted partner agree to exchange identity 
provider metadata, and then you create references to the trusted partner’s identity provider or service 
provider in your Identity Server configuration. You can obtain metadata via a URL or an XML 
document, then enter it in the system when you create the reference. 
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Embedded Service Providers 


In addition to setting up trust with internal or external service providers, you can reference ESPs in 
your enterprise. An ESP uses the Liberty protocol and does not require metadata entry, because this 
exchange happens automatically. The ESP comes with Access Manager and is embedded in Access 
Gateways. The ESP facilitates authentication between Identity Server and the resource protected by 
the device, as shown in as shown in Figure 3-20. 


Figure 3-20 Embedded Service Provider 


Payroll Identity Server (IDP) 


© 
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E 


Trusted ESP Mae mm Protected 
> a Application 
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Access Gateway 


Configuration Overview 


The following high-level tasks describe the process required to set up the trust model between an 
identity provider and a service provider. Although these tasks assume that both providers are Identity 
Servers provided with Access Manager, similar tasks must be performed when one of the providers is 
a third-party application. 


Administrators at each company install and configure Identity Server. 


See “Creating a Cluster Configuration” on page 67. (You must already be familiar with the 
Installing the Identity Servers in the NetIQ Access Manager 4.3 Installation and Upgrade Guide) 


. Administrators at each company must import the trusted root certificate of the other Identity 


Server into the NIDP trust store. 


Click Devices > Identity Servers > Servers > Edit > Security > NIDP Trust Store, then auto 
import the certificate. Use the SSL port (8443) even if you haven't set up the base URL of 
Identity Server to use HTTPS. 


. Administrators must exchange Identity Server metadata with the trusted partner. 


Metadata is generated by Identity Server and can be obtained via a URL or an XML document, 
then entered in the system when you create the reference. This step is not applicable if you are 
referencing an ESP. When you reference an ESP, the system lists the installed ESPs for you to 
choose, and no metadata entry is required. 


. Create the reference to the trusted identity provider and the service provider. 


This procedure associates the metadata with the new provider. See “Creating a Trusted Service 
Provider” on page 183. 


. Configure user authentication. 


This procedure defines how your Identity Server interacts with the trusted provider during user 
authentication. Access Manager comes with default basic authentication settings already 
enabled. See Chapter 5.2, “Federated Authentication,” on page 428. 
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3.9.2.1 


Additional important steps for enabling authentication between trusted providers include: 


+ Setting up the necessary authentication contracts. See Section 5.1.4, “Configuring 
Authentication Contracts,” on page 379. 


+ Enabling the profiles that you are using. See “Managing Web Services and Profiles” on 
page 517. 


+ Enabling the Always Allow Interaction option on the Web Service Consumer page. See 
“Configuring the Web Service Consumer” on page 525. 


6. (Conditional) If you are setting up SAML 1.1 federation, the protocol does not allow the target link 
after federation to be automatically configured. You must manually configure this setting. 


See “Specifying the Intersite Transfer Service URL for the Login URL Option” on page 196. 


NOTE: For a tutorial that explains all the steps for setting up federation between two NetIQ Identity 
Servers, see Section 5.2.1, “Configuring Federation,” on page 429. 


Configuring General Provider Settings 


The following settings are global. These affect any identity providers or identity consumers (service 
providers) that Identity Server has been configured to trust: 

¢ Section 3.9.2.1, “Configuring the General Identity Provider Settings,” on page 177 

¢ Section 3.9.2.2, “Configuring the General Identity Consumer Settings,” on page 179 

¢ Section 3.9.2.3, “Configuring the Introductions Class,” on page 179 

¢ Section 3.9.2.4, “Configuring the Trust Levels Class,” on page 180 


Configuring the General Identity Provider Settings 
The following settings affect all identity providers that Identity Server has been configured to trust. 


1 Click Devices > Identity Servers > Edit > Identity Providers. 
2 To specify identity provider settings, fill in the following fields: 


Show logged out providers: Displays logged-out providers on the identity provider’s logout 
confirmation page. 


Require Signed Authentication Requests: Specifies that for the Liberty 1.2 and SAML 2.0 
protocols, authentication requests from service providers must be signed. When you enable this 
option for the identity provider, you must also enable the Sign Authentication Requests option 
under the Identity Consumer heading on this page for the external trusted service provider. 


Use Introductions (Publish Authentications): Enables single sign-on from the service 
provider to the identity provider. The service provider determines the identity providers that users 
are already logged into, and then selectively and automatically asks for authentication from one 
of the identity providers. Introductions are enabled only between service and identity providers 
that have agreed to a circle of trust, which means that they have agreed upon a common domain 
name for this purpose. 


After authenticating a user, the identity provider accesses a service at the service domain and 
writes a cookie to the common part of the service domain, publishing that the authentication has 
occurred. 
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Service Domain (Local and Common): Enables a service provider to access a service at the 
service domain prior to authenticating a user. This service reads cookies obtained at this domain 
and discovers if any identity providers have provided authentication to the user. The service 
provider determines whether any of these identity providers can authenticate a user without 
credentials. The service domain must resolve to the same IP address as the base URL domain. 


For example, if an agreed-upon common domain is xyz.com, the service provider can specify a 
service domain of sp.xyz.com, and the identity provider can specify a service domain of 
idp.xyz.com. For the identity provider, xyz.com is the common value entered, and idp is the local 
value. 


Port: The port to use for identity provider introductions. Port 8445 for HTTPS is the default and 
must be opened on your firewall. If you specify a different port, you must edit the Tomcat 
server.xml file. 


SSL Certificate: Displays the Keystore page that you use to locate and replace the test-provider 
SSL certificate for this configuration. 


Identity Server comes with a test-provider certificate that you must replace for your production 
environment. This certificate is used for identity provider introductions. You can replace the test 
certificate now or after you have configured Identity Server. If you create the certificate and 
replace the test-connector now, you can save some time by restarting Tomcat only once. Tomcat 
must be restarted whenever you assign an Identity Server to a configuration and whenever you 
update a certificate key store. See “Managing the Keys, Certificates, and Trust Stores” on 

page 904. 


3 Click OK, then update Identity Server. 


Configuring a Global White List of Target URLs 


Many applications and services require URL redirection, which can cause security risks. While 
redirecting, the request can be tampered to redirect users to an external, malicious site. To prevent 
such issues, you can configure a list of permissible domains. Redirection is allowed only to these 
configured domains. 

1 Click Devices > Identity Servers > Edit > Identity Providers. 

2 Under Redirection White List, click New. 

3 Specify Domain. 


You can specify a domain name with an asterisk wildcard character (*) that represents the entire 
DNS subtree. For example, specifying * .example . com as a domain allows redirection to all 
children domain under examle.com including example.com. The Www prefix is not required. You 
can specify the asterisk (*) wildcard only at the lowest level of the subtree. 


For example: 

Valid domain name: *.example.com 

Invalid domain name: innerweb. *.com. 

You must configure at least one domain to prevent open redirection. 


¢ Liberty: The target parameter is filtered. If the requested target is not the white list, Identity 
Server does not login. 


+ WS-Fed: The wreply parameter is filtered. If the requested wreply is not in the white list, 
Identity Server does not login. However, if wreply is same as the provider's single logout or 
single sign-on URL domain, the request is accepted. 


+ SAML2: For idpsend, the target parameter is filtered using this list. This list is not 
applicable for spsend. 
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3.9.2.2 Configuring the General Identity Consumer Settings 


The following settings affect all identity consumers (service providers) that Identity Server has been 
configured to trust. 


1 Click Devices > Identity Servers > Edit > Identity Consumer. 
2 Specify whether Identity Server can run as an identity consumer. 


When Identity Server is configured to run as an identity consumer, Identity Server can receive 
(consume) authentication assertions from other identity providers. 


Enable: Enables this site to function as service provider. This setting is enabled by default. 


If this option is disabled, Identity Server cannot trust or consume authentication assertions from 
other identity providers. You can create and enable identity providers for the various protocols, 
but they are not loaded or used until this option is enabled. 


Require Signed Assertions: Specifies that all SAML assertions received by the service 
provider are signed by the issuing SAML authority. The signing authority uses a key pair to sign 
SAML data sent to this trusted provider. 


Sign Authentication Requests: Specifies that the service provider signs authentication 
requests sent to an identity provider when using the Liberty 1.2 and SAML 2.0 protocols. 


Use Introductions (Discover IDP Authentications): Enables a service provider to discover 
whether a user has authenticated to a trusted identity provider, so the user can use single sign- 
on without requiring authentication credentials. 


+ Service domain: The shared, common domain for all providers in the circle of trust. This 
domain must resolve to the same IP address as the base URL domain. You must enable the 
Identity Consumer option to enable this field. 


+ Port: The port to use for identity consumer introductions. Port 8446 for HTTPS is the default 
and must be opened on your firewall. If you specify a different port, you must edit the 
Tomcat server . xml file. 


IMPORTANT: If you enable the Use Introductions option and you want to allow your users to 
select which identity provider to use for authentication rather than use single sign-on, you need 
to configure the Introductions class. See “Configuring the Introductions Class” on page 179. 


SSL Certificate: Displays the Keystore page that you use to locate and replace the test- 
consumer SSL certificate for this configuration. 


Identity Server comes with a test-consumer certificate that you must replace for your production 
environment. This certificate is used for identity consumer introductions. You can replace the test 
certificate now or after you have configured Identity Server. If you create the certificate and 
replace the test-connector now, you can save some time by restarting Tomcat only once. Tomcat 
must be restarted whenever you assign an Identity Server to a configuration and whenever you 
update a certificate key store. See “Managing the Keys, Certificates, and Trust Stores” on 

page 904. 


3 Click OK, then update Identity Server. 


3.9.2.3 Configuring the Introductions Class 


The Introduction class determines whether the user can select an identity provider to trust when 
Identity Server is acting as a service provider. The default behavior is for introductions to happen 
automatically, thus allowing single sign-on. Identity Server passively checks with the identity 
providers, one at time, to see if they can authenticate the service provider. If the identity provider can 
authenticate the user and the Introductions class is enabled, the user is presented with one or more 
cards that look similar to the following: 
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AQ 
AG Card has been used to authenticate 
t 


The small check mark indicates to the user that this is a possible card. When the user mouses over 
the card, the description appears. If the user selects one of these cards, the user is automatically 
authenticated. 


To configure the Introductions class: 


1 Click Devices > Identity Server > Servers > Edit > Local > Classes > Introductions. 
2 Click Properties > New, then specify the following values. 
Property Name: Specify ShowUser. 
Property Value: Specify true. 
3 Click OK. 
4 Return to the Servers page, then update the Identity Server. 


5 When you configure this class, you need to also enable the Use Introductions option. Continue 
with “Configuring the General Identity Consumer Settings” on page 179. 


Configuring the Trust Levels Class 


The Trust Levels class allows you to specify an authentication level or rank for class types that do not 
appear on the Defaults page and for which you have not defined a contract. The level is used to rank 
the requested type. Using the authentication level and the comparison context, Identity Server can 
determine whether any contracts meet the requirements of the request. If one or more contracts 
match the request, the user is presented with the appropriate authentication prompts. For more 
information and other configuration options, see Section 5.1.5, “Specifying Authentication Defaults,” 
on page 387 and “Specifying Authentication Types” on page 388 
1 Click Devices > Identity Server > Servers > Edit > Local > Classes > Trust Levels. 
2 Click Properties > New, then specify the following values. 
Property Name: Specify SetClassTrustLevels. 
Property Value: Specify true. 
3 For each class type for which you want to set a level, create a property for that class. 


3a Set the Property Name to the name of the class. For example, use one of the following: 


urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession 
urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol 


For additional values, refer to the SAML2 and Liberty Authentication Context Specifications. 


3b Set the Property Value to the security level or rank you want for the class. A level of 2 is 
higher than a level of 1. 


4 Click OK, then update the Identity Server. 
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3.9.3.1 


Managing Trusted Providers 


The procedure for establishing trust between providers begins with obtaining metadata for the trusted 
provider. If you are using the NetIQ Identity Server, protocol-specific metadata is available via a URL. 
1 Click Devices > Identity Servers > Servers > Edit > [Protocol]. 
For the protocol, select Liberty, SAML 1.1 or SAML 2.0. 
2 Select one of the following actions: 


New: Launches the Create Trusted Identity Provider Wizard or the Create Trusted Service 
Provider Wizard, depending on your selection. See one of the following for more information:. 


+ “Creating a Trusted Service Provider” on page 183 

¢ “Creating a Trusted Identity Provider” on page 181 
Delete: Allows you to delete the selected identity or service provider. 
Enable: Enables the selected identity or service provider. 


Disable: Disables the selected identity or service provider. When a provider is disabled, the 
server does not load the definition. The definition is not deleted, and at a future time, the provider 
can be enabled. 


IMPORTANT: When selecting which protocol to use, be aware of logout behavior of the SAML 1.1 
protocol. The SAML 2.0 and Liberty 1.2 protocols define a logout mechanism whereby the service 
provider sends a logout command to the trusted identity provider when a user logs out at a service 
provider. SAML 1.1 does not provide such a mechanism. For this reason, when a logout occurs at the 
SAML 1.1 service provider, no logout occurs at the trusted identity provider. A valid session is still 
running at the identity provider, and no credentials need to be entered. In order to log out at both 
providers, the user must navigate to the identity provider that authenticated him to the SAML 1.1 
service provider and log out manually. 


Creating a Trusted Identity Provider 


Before you can create a trusted identity provider, you must complete the following tasks: 
+ Imported the trusted root of the provider's SSL certificate into the NIDP trust store. For 
instructions, see “Managing the Keys, Certificates, and Trust Stores” on page 904. 


¢ Shared the trusted root of the SSL certificate of your Identity Server with the identity provider so 
that the administrator can imported it into the identity provider’s trust store. 


+ Obtained the metadata URL from the identity provider, an XML file with the metadata, or the 
information required for manual entry. For more information about the manual entry option, see 
“Editing a SAML 1.1 Identity Provider’s Metadata” on page 191. 


¢ Shared the metadata URL of your Identity Server with the identity provider or an XML file with the 
metadata. 


¢ Enabled the protocol. Click Devices > Identity Servers > Edit, and on the Configuration page, 
verify that the required protocol in the Enabled Protocols section has been enabled. 


To create an identity provider: 


1 Click Devices > Identity Servers > Servers > Edit > SAML 1.1, SAML 2.0, or Liberty. 
2 Click New, then click Identity Provider. 

3 In the Name option, specify a name by which you want to refer to the provider. 

4 Select one of the following sources for the metadata: 
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Metadata URL: Specify the metadata URL for a trusted provider. The system retrieves protocol 
metadata using the specified URL. Examples of metadata URLs for an Identity Server acting as 
an identity provider with an IP address of 10.1.1.1: 


http://10.1.1.1:8080/nidp/saml/metadata 
https://10.1.1.1:8443/nidp/saml/metadata 


The default values nidp and 8080 are established during product installation; nidp is the Tomcat 
application name. If you have set up SSL, you can use https and port 8443. 


If your Identity Server and Administration Console are on different machines, use HTTP to import 
the metadata. If you are required to use HTTPS with this configuration, you must import the 
trusted root certificate of the provider into the trust store of Administration Console. You need to 
use the Java keytool to import the certificate into the cacerts file in the security directory of 
Administration Console. 


The cacerts file is located at: 
Linux: /opt/novell/java/jre/lib/security 
Windows Server 2012: \Program Files (x86)\Novell\jre\lib\security 


If you do not want to use HTTP and you do not want to import a certificate into Administration 
Console, you can use the Metadata Text option. In a browser, enter the HTTP URL of the 
metadata. View the text from the source page, save the source metadata, then paste it into the 
Metadata Text option. 


Metadata Text: An editable field in which you can paste copied metadata text from an XML 
document, assuming you obtained the metadata via e-mail or disk and are not using a URL. If 
you copy metadata text from a web browser, you must copy the text from the page source. 


Manual Entry: (SAML 1.1) Allows you to enter metadata values manually. When you select this 
option, the system displays the Enter Metadata Values page. See “Editing a SAML 1.1 Identity 
Provider’s Metadata” on page 191. 


Metadata Repositories: (SAML 1.1 and SAML 2.0) Allows you to configure several identity and/ 
or service providers using a multi-entity metadata file available in a central repository. 


5 Click Next. 
6 Review the metadata certificates, then click OK. 


Configure an authentication card to use with this identity provider. Fill in the following fields: 


ID: (Optional) Specify an alphanumeric value that identifies the card. If you need to reference 
this card outside of Administration Console, you need to specify a value here. If you do not 
assign a value, Identity Server creates one for its internal use 


Text: Specify the text that is displayed on the card to the user. 


Login URL: Specify an Intersite Transfer Service URL.The URL has the following format, where 
idp.sitea.novell.com is the DNS name of the identity provider and idp.siteb.novell.com is the 
name of the service provider: 


NOTE: The PID in the login URL must exactly match the entity ID specified in the metadata. 


https://idp.sitea.novell.com:8443/nidp/saml/idpsend?PID=https:// 
idp.siteb.novell.com:8443/nidp/saml/metadata&TARGET=https:// 
idp.siteb.novell.com:8443/nidp/app 


For more information, see “Specifying the Intersite Transfer Service URL for the Login URL 
Option” on page 196. 


Image: Specify the image to be displayed on the card. Select the image from the drop down list. 
To add an image to the list, click <Select local image>. 
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Show Card: Determine whether the card is shown to the user, which allows the user to select 
and use the card for authentication. If this option is not selected, the card is only used when a 
service provider makes a request for the card. 


8 Click Finish. The system displays the trusted provider on the protocol page. 
9 Update Identity Server. 


The wizard allows you to configure the required options and relies upon the default settings for 
the other options. For information about how to configure the default settings and how to 
configure the other available options, see Section 3.9.4, “Modifying a Trusted Provider,” on 
page 185. 


Creating a Trusted Service Provider 


You can configure Identity Server to trust a service provider or an identity provider. 
+ When you create a trusted identity provider, you are allowing that identity provider to 
authenticate the user and Identity Server acts as a service provider. 
+ When you create a trusted service provider, you are configuring Identity Server to provide 
authentication for the service provider and Identity Server acts as an identity provider. 


Both of these types of trust relationships require the identity provider to establish a trusted 
relationship with the service provider and the service provider to establish a trusted relationship with 
the identity provider. 


The default settings of identity and service providers when you import the metadata repository are as 
follows: 
¢ SAML 1.1 Identity Provider 
e No contracts associated to Satisfiable list of IDP 
+ No image selected for the IDP card 
¢ Login URL will be empty with Show card disabled. 
¢ No attribute set associated 


+ SAML 1.1 Service Provider 
+ No contracts associated to Satisfiable list of SP 
+ No Attribute set associated 


¢ SAML 2.0 Identity Provider 
+ Persistent Federation as the Name Identifier 
+ Post Binding 
+ No contracts associated to Satisfiable list of IDP 
+ No image selected for the IDP card 
+ No Attribute set associated 


¢ SAML 2.0 Service Provider 
¢ No contracts associated to Satisfiable list of SP 
+ Post Binding 
+ No Attribute set associated 
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Prerequisites 
Before you can create a trusted provider, you must complete the following tasks: 
+ Imported the trusted root of the provider's SSL certificate into the NIDP trust storeFor 
instructions, see “Managing the Keys, Certificates, and Trust Stores” on page 904.. 


¢ Shared the trusted root of the SSL certificate of your Identity Server with the other provider so 
that the administrator can imported it into the provider's trust store. 


+ Obtained the metadata URL from the other provider or an XML file with the metadata. 


+ Shared the metadata URL of your Identity Server with the other provider or sent an XML file with 
the metadata. 


+ Enabled the protocol. Click Devices > Identity Servers > Edit, and on the Configuration page, 
verify that the required protocol in the Enabled Protocols section has been enabled. 


Procedure 


1 Click Devices > Identity Servers > Edit > [Protocol]. 
2 Click New, then click Service Provider. 


NOTE: By default, the Provider Type > General is selected. You can configure an Identity Server 
to trust a service provider to establish federation with external service providers. For more 
information on pre-configured metadata for Google Applications, Office 365, and 
Salesforce.com, see Chapter 5.2.11, “Configuring Authentication Through Federation for 
Specific Providers,” on page 616. 


3 Select one of the following sources for the metadata: 


Metadata URL: Specify the metadata URL for a trusted provider. The system retrieves protocol 
metadata by using the specified URL. 


Examples of metadata URLs for an Identity Server acting as a trusted provider with an IP 
address 10.1.1.1: 


¢ Liberty: 
http://10.1.1.1:8080/nidp/idff/metadata 
https://10.1.1.1:8443/nidp/idff/metadata 

* SAML: 
http://10.1.1.1:8080/nidp/sam12/metadata 
https://10.1.1.1:8443/nidp/sam12/metadata 

+ OIOSAML: 
http://10.1.1.1/nidp/sam12/metadata_oiosaml 
https://10.1.1.1/nidp/sam12/metadata_oiosaml 

¢ SAML 1.1: 
http://10.1.1.1:8080/nidp/saml/metadata 
https://10.1.1.1:8443/nidp/saml/metadata 


The default values nidp and 8080 are established during product installation; nidp is the Tomcat 
application name. If you have set up SSL, you can use https and port 8443. 
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N 


+ 


+ 


+ 


If your Identity Server and Administration Console are on different machines, use HTTP to import 
the metadata. If you are required to use HTTPS with this configuration, you must import the 
trusted root certificate of the provider into the trust store of Administration Console. You need to 
use the Java keytool to import the certificate into the cacerts file in the security directory of 
Administration Console. 


Linux: /opt/novell/java/jre/lib/security 
Windows Server 2012: \Program Files (x86)\Novell\jre\lib\security 


If you do not want to use HTTP and you do not want to import a certificate into Administration 
Console, you can use the Metadata Text option. In a browser, enter the HTTP URL of the 
metadata. View the text from the source page, save the source metadata, then paste it into the 
Metadata Text option. 


Metadata Text: An editable field in which you can paste copied metadata text from an XML 
document, assuming you obtained the metadata via e-mail or disk and are not using a URL. If 
you copy metadata text from a web browser, you must copy the text from the page source. 


Manual Entry: Allows you to enter metadata values manually. When you select this option, the 
system displays the page to enter the required details. See “Editing a SAML 2.0 Service 
Provider’s Metadata” on page 190 or “Editing a SAML 1.1 Service Provider’s Metadata” on 
page 192. 


Metadata Repositories: Allows you to configure several identity and/or service providers using 
a multi-entity metadata file available in a central repository. 


In the Name option, specify a name by which you want to refer to the provider. 


5 Click Next. 
6 Review the metadata certificates and click Finish. The system displays the trusted provider on 


the protocol page. 
Click OK, then update Identity Server. 


The wizard allows you to configure the required options and relies upon the default settings for 
the other federation options. For information about how to configure the default settings and how 
to configure the other available options, see Section 3.9.4, “Modifying a Trusted Provider,” on 
page 185. 


Modifying a Trusted Provider 


The following sections describe the configuration options available for identity providers and service 
providers: 


You can modify the following features of an identity provider: 


Communication Security: See Section 3.9.5, “Communication Security,” on page 186. 


Attributes to Obtain at Authentication: See “Configuring the Attributes Obtained at 
Authentication” on page 187. 


Metadata: See Section 3.9.7, “Managing Metadata,” on page 189. 


Authentication Request: See “Configuring a SAML 2.0 Authentication Request” on page 483 
and “Configuring a Liberty Authentication Request” on page 513. 


User Identification: See Chapter 5.2, “Federated Authentication,” on page 428. 


Authentication Card: See “Modifying the Authentication Card for Liberty or SAML 2.0” on 
page 492 and “Modifying the Authentication Card for SAML 1.1” on page 508. 


You can modify the following features of a service provider: 


Communication Security: See Section 3.9.5, “Communication Security,” on page 186. 
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¢ Attributes to Send in the Response: See “Configuring the Attributes Sent with Authentication” 
on page 188. 


¢ Intersite Transfer Service: See “Configuring an Intersite Transfer Service Target for a Service 
Provider” on page 199. 


¢ Metadata: See Section 3.9.7, “Managing Metadata,” on page 189. 


+ Authentication Response: See Section 3.9.8, “Configuring an Authentication Response for a 
Service Provider,” on page 193. 


Communication Security 


The communication security settings control the direct communication between Identity Server and a 
trusted provider across the SOAP back channel. You can secure this channel with one of three 
methods: 


Message Signing: This is the default method, and Identity Server comes with a test signing 
certificate that is used to sign the back-channel messages. We recommend replacing this test signing 
certificate with a certificate from a well-known certificate authority. This method is secure, but it is 
CPU intensive. For information about replacing the default certificate, see “Managing the Keys, 
Certificates, and Trust Stores” on page 904. 


Mutual SSL: This method is probably the fastest method, and if you are fine-tuning your system for 
performance, you must select this method. However, it requires the exchange of trusted root 
certificates between Identity Server and the trusted provider. This exchange of certificates is a 
requirement for setting up the trust relationship between the two providers. To verify that you have 
exchanged certificates, see “Managing the Keys, Certificates, and Trust Stores” on page 904. 


Basic Authentication: This method is as fast as mutual SSL and the least expensive because it 
does not’ require any certificates. However, it does require the exchange of usernames and 
passwords with the administrator of the trusted provider, which might or might not compromise the 
security of the trusted relationship. 


If your trusted provider is another Identity Server, you can use any of these methods, as long as your 
Identity Server and the trusted Identity Server use the same method. If you are setting up a trusted 
relationship with a third-party provider, you need to select a method supported by that provider. 


For configuration information, see the following sections: 
¢ “Configuring Communication Security for a SAML 2.0 Identity Provider” on page 486 
¢ “Configuring Communication Security for a SAML 2.0 Service Provider” on page 482 


¢ “Configuring Communication Security for SAML 1.1” on page 507 
¢ “Configuring Communication Security for Liberty” on page 512 
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3.9.6.1 


Selecting Attributes for a Trusted Provider 


You can select attributes that an identity provider sends in an authentication request or that a service 
provider receives in an authentication response. The attributes are selected from an attribute set, 
which you can create or select from a list of already defined sets (see Section 3.5.1, “Configuring 
Attribute Sets,” on page 80). 


For best performance, you must configure the trusted providers to use attribute sets, especially for 
attributes that have static values such as a user's e-mail address, employee ID, or phone number. It 
reduces the traffic between the provider and the LDAP server, because the attribute information can 
be gathered in one request at authentication rather than in a separate request for each attribute when 
a policy or protected resource needs the attribute information. 

¢ Section 3.9.6.1, “Configuring the Attributes Obtained at Authentication,” on page 187 

¢ Section 3.9.6.2, “Configuring the Attributes Sent with Authentication,” on page 188 


¢ Section 3.9.6.3, “Sending Attributes to the Embedded Service Provider,” on page 188 


Configuring the Attributes Obtained at Authentication 


When Identity Server creates its request to send to the identity provider, it uses the attributes that you 
have selected. The request asks the identity provider to provide values for these attributes. You can 
then use these attributes to create policies, to match user accounts, or if you allow provisioning, to 
create a user account on the service provider. 

1 Click Devices > Identity Servers > Edit > [Protocol] > [Identity Provider] > Attributes. 


2 (Conditional) To create an attribute set, select New Attribute Set from the Attribute Set drop- 
down menu. 


An attribute set is a group of attributes that can be exchanged with the trusted provider. For 
example, you can specify that the local attribute of any attribute in the Liberty profile (such as 
Informal Name) matches the remote attribute specified at the service provider. 


2a Specify a set name, then click Next. 

2b On the Define Attributes page, click New. 

2c Select a local attribute. 

2d Optionally, provide the name of the remote attribute and a namespace. 
2e Click OK. 


For more information about this process, see Section 3.5.1, “Configuring Attribute Sets,” on 
page 80. 


2f To add other attributes to the set, repeat Step 2b through Step 2e. 
2g Click Finish. 
3 Select an attribute set 
4 Select attributes from the Available list, and move them to the left side of the page. 


The attributes that you move to the left side of the page are the attributes you want to be 
obtained during authentication. 


5 Click OK twice. 
6 Update Identity Server. 
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When Identity Server creates its response for the service provider, it uses the attributes listed on the 
Attributes page. The response needs to contain the attributes that the service provider requires. If you 
do not own the service provider, you need to contact the administrator of the service provider and 
negotiate which attributes you need to send in the response. The service provider can then use these 
attributes to identify the user, to create policies, to match user accounts, or if it allows provisioning, to 
create a user accounts on the service provider. 

1 Click Devices > Identity Servers > Edit > [Protocol] > [Service Provider] > Attributes. 


2 (Conditional) To create an attribute set, select New Attribute Set from the Attribute Set drop- 
down menu. 


An attribute set is a group of attributes that can be exchanged with the trusted provider. For 
example, you can specify that the local attribute of any attribute in the Liberty profile (Such as 
Informal Name) matches the remote attribute specified at the service provider. 


2a Specify a set name, then click Next. 

2b On the Define Attributes page, click New. 

2c Select a local attribute. 

2d Optionally, you can provide the name of the remote attribute and a namespace. 
2e Click OK. 


For more information about this process, see Section 3.5.1, “Configuring Attribute Sets,” on 
page 80. 


2f To add other attributes to the set, repeat Step 2b through Step 2e. 
2g Click Finish. 
3 Select an attribute set 
4 Select attributes from the Available list, and move them to the left side of the page. 


The left side of the page lists the attributes that you want sent in an assertion to the service 
provider. 


5 Click OK twice. 
6 Update Identity Server. 


3.9.6.3 Sending Attributes to the Embedded Service Provider 


You can configure the Embedded Service Provider (ESP) of Access Gateway to receive attributes 
when the user authenticates. LDAP traffic is reduced and performance is improved when the required 
LDAP attribute values are retrieved during authentication. This improvement is easily seen when you 
have many users and you have configured Identity Injection or Authorization policies to protect 
resources and these policies use LDAP attributes or Identity Server roles. 


When the authentication process does not gather the LDAP attribute values, each user access can 
generate a new LDAP query, depending upon how the user accesses the resources and how the 
policies are defined. However, if the LDAP values are gathered at authentication, one LDAP query 
can retrieve all the needed values for the user. 


1 Click Devices > Identity Servers > Shared Settings. 
2 On the Attributes page, click New, specify a name, then click Next. 
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3 For each attribute you need to add because it is used in a policy: 
3a Click New. 


3b In the Local attribute drop-down list, scroll to LDAP Attribute section, then select the 
attribute. 


3c Click OK. 
The other fields do not need to be configured. 


4 If you use Identity Server roles in your policies, click New, select the All Roles attribute, then click 
OK. 


5 Click Finish. 
This saves the attribute set. 
6 Click Servers > Edit > Liberty. 
7 Click the name of the Embedded Service Provider. 


If the Embedded Service Provider is part of a cluster of Access Gateways, the default name is 
the cluster name. If Access Gateway is not part of a cluster, the default name is the IP address of 
Access Gateway. 


8 Click Attributes. 

9 For the attribute set, select the set you created for the Embedded Service Provider. 
10 Select attributes from the Available list, then move them to the left side of the page. 
11 Click OK, then update Identity Server. 


Managing Metadata 


The Liberty, SAML 1.1, and SAML 2.0 protocols contain pages for viewing and reimporting the 
metadata of the trusted providers. 
¢ Section 3.9.7.1, “Viewing and Reimporting a Trusted Provider’s Metadata,” on page 189 
¢ Section 3.9.7.2, “Viewing Trusted Provider Certificates,” on page 190 
¢ Section 3.9.7.3, “Editing a SAML 2.0 Service Provider’s Metadata,” on page 190 
¢ Section 3.9.7.4, “Editing a SAML 1.1 Identity Provider’s Metadata,” on page 191 
¢ Section 3.9.7.5, “Editing a SAML 1.1 Service Provider’s Metadata,” on page 192 


Viewing and Reimporting a Trusted Provider’s Metadata 


You might need to reimport a trusted provider's metadata if you learn that it has changed. The 
metadata changes when you change the provider to use HTTPS rather than HTTP and when you 
change the certificate that it is using for SSL. The steps for reimporting the metadata are similar for 
Liberty and SAML protocols. 


NOTE: The trusted providers that are from the metadata repository cannot be reimported from this 
option. Go to Shared Settings > > Metadata Repositories and click on the metadata repository 
created to reimport the trusted provider. 


1 Click Devices > Identity Servers > Edit > [Protocol]. 
2 Click the trusted provider, then click the Metadata tab. 
This page displays the current metadata the trusted provider is using. 
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3 To reimport the metadata: 


3a Copy the URL in the providerID field (Liberty) or the entityID (SAML). 


3b (SAML 1.1) Paste the URL to a file, click Authentication Card, copy the Login URL to the 
file, then click Metadata. 


3c Click Reimport. 
3d Follow the prompts to import the metadata. 
For the metadata URL, paste in the value you copied. 


If your Administration Console is installed with your Identity Server, you need to change the 
protocol from HTTPS to HTTP and the port from 8443 to 8080. 


4 Confirm metadata certificates, then click Finish, or for an identity provider, click Next. 
5 (Identity Provider) Configure the card, then click Finish. 


For SAML 1.1, copy the value you saved into the Login URL. 


6 Update Identity Server. 


NOTE: Reimport support is not available for SAML 1.1 and SAML 2.0 protocols. 


Viewing Trusted Provider Certificates 


You can review and confirm the certificate information for identity and service providers. 


1 Click Devices > Identity Servers > Edit > [Protocol] > [Name of Provider] > Metadata > 


Certificates. 

View the following information is displayed for the certificates: 

Subject: The subject name assigned to the certificate. 

Validity: The first date the certificate was valid, and the date the certificate expires. 

Issuer DN: The distinguished name of the Certificate Authority (CA) that created the certificate. 
Algorithm: The name of the algorithm that was used to create the certificate. 

Serial Number: The serial number that the CA assigned to the certificate. 


3 Click OK if you are viewing the information, or click Next or Finish if you are creating a provider. 


Editing a SAML 2.0 Service Provider’s Metadata 


Access Manager allows you to obtain metadata for SAML 2.0 providers. However, metadata for 
SAML 2.0 might not be available for some service providers, so you can enter the metadata manually. 
The page for this is available if you clicked the Manual Entry option when you created the trusted 
provider. 


1 Click Devices > Identity Servers > Edit > SAML 2.0 > [Service Provider] > Metadata. 


You can reimport the metadata (see Step 2) or edit it (see Step 3). 


2 To reimport the metadata, click Reimport on the View page. 


Follow the on-screen instructions to complete the steps in the wizard. 


3 To edit the metadata manually, click Edit. 
4 Fill in the following fields: 
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Provider ID: (Required) Specifies the SAML 2.0 metadata unique identifier for the provider. For 
example, https://<dns>:8443/nidp/sam12/metadata. Replace <dns> with the DNS name of 
the provider. 


In the metadata, this is the entityID value. 
Metadata expiration: Specifies the date upon which the metadata is no longer valid. 


Want assertion to be signed: Specifies that authentication assertions from the trusted provider 
must be signed. 


Artifact consumer URL: Specifies where the partner receives incoming SAML artifacts. For 
example, https: //<dns>:8443/nidp/sam12/spassertion_consumer. Replace <dns> with the 
DNS name of the provider. 


In the metadata, this URL value is found in the AssertionConsumerService section of the 
metadata. 


Post consumer URL: Specifies where the partner receives incoming SAML POST data. For 
example, https: //<dns>:8443/nidp/sam12/spassertion_consumer. Replace <dns> with the 
DNS name of the provider. 


In the metadata, this URL value is found in the AssertionConsumerService section of the 
metadata. 


Service Provider: Specifies the public key certificate used to sign SAML data. You can browse 
to locate the service provider certificate. 


5 Click Finish. 


Editing a SAML 1.1 Identity Provider’s Metadata 


Access Manager allows you to import metadata for SAML 1.1 providers. However, metadata for 
SAML 1.1 might not be available for some trusted providers, so you can enter metadata manually. 
The page for this is available if you clicked the Manual Entry option when you created the trusted 
provider. 
1 Click Devices > Identity Servers > Edit > SAML 1.1 > [Identity Provider] > Metadata. 
You can reimport the metadata (see Step 2) or edit it (see Step 4). 
2 To reimport the metadata from a URL or text, click Reimport on the View page. 


The system displays the Create Trusted Identity Provider Wizard that lets you obtain the 
metadata. Follow the on-screen instructions to complete the steps in the wizard. 


3 Select either Metadata URL or Metadata Text, then fill in the field for the metadata. 
4 To edit the metadata manually, click Edit. 
5 Fill in the following fields as necessary: 


Supported Version: Specifies the version of SAML that you want to use. You can select SAML 
1.0, SAML 1.1, or both SAML 1.0 and SAML 1.1. 


Provider ID: (Required) The SAML 1.1 metadata unique identifier for the provider. For example, 
https://<dns>:8443/nidp/saml/metadata. Replace <dns> with the DNS name of the 
provider. 


In the metadata, this is the entityID value. 


Source ID: The SAML Source ID for the trusted provider. The Source ID is a 20-byte value that 

is used as part of the Browser/Artifact profile. It allows the receiving site to determine the source 

of received SAML artifacts. If none is specified, the Source ID is auto-generated by using a SHA- 
1 hash of the site provider ID. 


Metadata expiration: The date upon which the metadata is no longer valid. 
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SAML attribute query URL: The URL location where an attribute query is to be sent to the 
partner. The attribute query requests a set of attributes associated with a specific object. A 
successful response contains assertions that contain attribute statements about the subject. A 
SAML 1.1 provider might use the base URL, followed by /saml/soap. For example, https: // 
<dns>:8443/nidp/saml/soap. Replace <dns> with the DNS name of the provider. 


In the metadata, this URL value is found in the AttributeService section of the metadata. 


Artifact resolution URL: The URL location where artifact resolution queries are sent. ASAML 
artifact is included in the URL query string. The target URL on the destination site the user wants 
to access is also included on the query string. ASAML 1.1 provider might use the base URL, 
followed by /saml/soap. For example, https: //<dns>:8443/nidp/saml1/soap. Replace <dns> 
with the DNS name of the provider. 


In the metadata, this URL value is found in the ArtifactResolutionService section of the 
metadata. 


To specify signing certificate settings, fill in the followi 
ng fields: 


Attribute authority: Specifies the signing certificate of the partner SAML 1.1 attribute authority. 
The attribute authority relies on the identity provider to provide it with authentication information 
so that it can retrieve attributes for the appropriate entity or user. The attribute authority must 
know that the entity requesting the attribute has been authenticated to the system. 


Identity provider: (Required) Appears if you are editing identity provider metadata. This field 
specifies the signing certificate of the partner SAML 1.1 identity provider. It is the certificate the 
partner uses to sign authentication assertions. 


7 Click OK. 
8 On Identity Servers page, click Update All to update the configuration. 


Editing a SAML 1.1 Service Provider’s Metadata 


Access Manager allows you to obtain metadata for SAML 1.1 providers. However, metadata for 
SAML 1.1 might not be available for some trusted providers, so you can enter the metadata manually. 
The page for this is available if you clicked the Manual Entry option when you created the trusted 
provider. 


For conceptual information about how Access Manager uses SAML, see Chapter 5.2.4.1, 
“Understanding How Access Manager Uses SAML,” on page 471. 


1 Click Devices > Identity Servers > Edit > SAML 1.1 > [Service Provider] > Metadata. 


You can reimport the metadata (see Step 2) or edit it (see Step 3). 
To reimport the metadata, click Reimport on the View page. 
Follow the on-screen instructions to complete the steps in the wizard. 


3 To edit the metadata manually, click Edit. 
4 Fill in the following fields: 


Supported Version: Specifies which version of SAML that you want to use. You can select 
SAML 1.0, SAML 1.1, or both SAML 1.0 and SAML 1.1. 


Provider ID: (Required) Specifies the SAML 1.1 metadata unique identifier for the provider. For 
example, https: //<dns>:8443/nidp/saml/metadata. Replace <dns> with the DNS name of 
the provider. 


In the metadata, this is the entityID value. 
Metadata expiration: Specifies the date upon which the metadata is no longer valid. 
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Want assertion to be signed: Specifies that authentication assertions from the trusted provider 
must be signed. 


Artifact consumer URL: Specifies where the partner receives incoming SAML artifacts. For 
example, https: //<dns>:8443/nidp/saml/spassertion_consumer. Replace <dns> with the 
DNS name of the provider. 


In the metadata, this URL value is found in the AssertionConsumerService section of the 
metadata. 


Post consumer URL: Specifies where the partner receives incoming SAML POST data. For 
example, https: //<dns>:8443/nidp/saml/spassertion_consumer. Replace <dns> with the 
DNS name of the provider. 


In the metadata, this URL value is found in the AssertionConsumerService section of the 
metadata. 


Service Provider: Specifies the public key certificate used to sign SAML data. You can browse 
to locate the service provider certificate. 


5 Click Finish. 


Configuring an Authentication Response for a Service 
Provider 


The Liberty and SAML 2.0 protocols support slightly different options for configuring how you want 
Identity Server to respond to an authentication request from a service provider. The SAML 1.1 
protocol does not support sending an authentication request. However, you can configure an Intersite 
Transfer Service (see Section 3.9.10, “Using the Intersite Transfer Service,” on page 194) to trigger a 
response from Identity Server. 


When Identity Server receives an authentication request from a trusted service provider, the request 
contains the conditions that Identity Server needs to fulfill. The Authentication Response page allows 
you to configure how you want Identity Server to fulfill the binding and name identifier conditions of 
the request, or for SAML 1.1, respond to the Intersite Transfer Service. For configuration information, 
see one of the following: 


¢ “Configuring the Liberty Authentication Response” on page 514 
¢ “Configuring A SAML 2.0 Authentication Response” on page 479 
¢ “Configuring the SAML 1.1 Authentication Response” on page 508 
The Defaults page allows you to specify which contract is used when the authentication request 


specifies a class or type rather than a contract. For more information, see Section 5.1.5, “Specifying 
Authentication Defaults,” on page 387. 


When the service provider sends an authentication request that specifies a specific contract, you 
need to ensure that Identity Server has a the contract matches the expected URI. For information 
about how to configure such a contract, see “Creating a Contract for a Specific Authentication Type” 
on page 388. 
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3.9.9 


3.9.10 


3.9.10.1 


Routing to an External Identity Provider Automatically 


When the NetIQ Identity Server is configured to federate with multiple external Identity Providers, 
administrator can specify the list of Authentication Contracts that an external provider can execute. 
This configuration allows the NetIQ Identity Server (acting as service provider) to automatically select 
the external identity provider without the user having to click on the external provider's card. 


Authentication Contracts in the NetIQ Identity Servers have been enhanced to be configured with an 
Authentication Class Reference. This reference can be used in federating with External Identity or 
Service Providers that only respond to AuthnContextClassRef in the Authentication Request and 
Response. For more information about setting up the contract mapping and adding contracts to the 
satisfiable list, see “Modifying the Authentication Card for Liberty or SAML 2.0” on page 492 and 
Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


Using the Intersite Transfer Service 


è Section 3.9.10.1, “Understanding the Intersite Transfer Service URL,” on page 194 


¢ Section 3.9.10.2, “Specifying the Intersite Transfer Service URL for the Login URL Option,” on 
page 196 


¢ Section 3.9.10.3, “Using Intersite Transfer Service Links on Web Pages,” on page 198 


¢ Section 3.9.10.4, “Configuring an Intersite Transfer Service Target for a Service Provider,” on 
page 199 


¢ Section 3.9.10.5, “Configuring Whitelist of Target URLs,” on page 200 


¢ Section 3.9.10.6, “Validating Incoming Authentication Request for Assertion Consumer Service 
URL,” on page 200 


¢ Section 3.9.10.7, “Federation Entries Management,” on page 201 


¢ Section 3.9.10.8, “Step up Authentication Example for an Identity Provider Initiated Single Sign- 
On Request,” on page 201 


¢ Section 3.9.10.9, “URL Query String Parameters,” on page 203 


Understanding the Intersite Transfer Service URL 


The Intersite Transfer Service is used by an identity provider to provide authentication to occur ata 
service provider that it trusts. The URLs for accessing the Intersite Transfer Service differ for each 
supported protocol (Liberty, SAML 1.1, and SAML 2.0). The NetIQ Access Manager identity and 
service provider components use the following format of the Intersite Transfer Service URL: 


<identity provider URL>?PID=<entityID>&TARGET=<final_destination_URL> 


The <identity provider URL> is the location where the authentication request can be processed. For 
an Access Manager Identity Server, the URL is the Base URL of the server that provides 
authentication, followed by the path to the protocol application being used for federation. 


For example: 

SAML 1.1: https://idp.sitea.novell.com:8443/nidp/saml/idpsend 
SAML 2.0: https://idp.sitea.novell.com:8443/nidp/sam12/idpsend 
Liberty: https://idp.sitea.novell.com:8443/nidp/idff/idpsend 


If a third-party server provides the authentication, refer the documentation for the format of this URL. 
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The <entityID> is the URL to the location of the metadata of the service provider. The scheme (http or 
https) in the <entityiD> must match what is configured for the </identity provider URL>. 


For SAML 1.1 and SAML 2.0, search the metadata for its entityID value. For Liberty, search the 
metadata for the providerlD value. Access Manager Identity Servers acting as service providers have 
the following types of values: 


SAML 1.1: https://idp.siteb.novell.com:8443/nidp/saml/metadata 
SAML 2.0: https://idp.siteb.novell.com:8443/nidp/sam12/metadata 
Liberty: https://idp.siteb.novell.com:8443/nidp/idff/metadata 


If you are setting up federations with a third-party service provider, refer the documentation for the 
URL or location of its metadata. 


The <final_destination_URL> is the URL to which the browser is redirected following a successful 
authentication at the identity provider. If this target URL contains parameters (for example, 
TARGET=https://login. provo.novell.com:8443/nidp/app?function_id=22166& 
amp;Resp_Id=55321 &amp;Resp_App_Id=810&amp; security_id=0), the URL must be encoded to 
prevent it from being truncated. 


For example: 


¢ SAML 1.1: https://idp.sitea.novell.com:8443/nidp/saml/idpsend?PID=https:// 
idp.siteb.novell.com:8443/nidp/saml/metadata&TARGET=https:// 
eng.provo.novell.com/sam1i/myapp 


+ SAML 2.0: https://idp.sitea.novell.com:8443/nidp/sam12/idpsend?PID=https:// 
idp.siteb.novell.com:8443/nidp/sam12/metadata&TARGET=https: // 
eng.provo.novell.com/sam12/myapp 


¢ Liberty: https://idp.sitea.novell.com:8443/nidp/idff/idpsend?PID=https:// 
idp.siteb.novell.com:8443/nidp/idff/metadata&TARGET=https:// 
eng.provo.novell.com/liberty/myapp 


To read more about configuring an intersite URL, see “Configuring an Intersite Transfer Service 
Target for a Service Provider” on page 199. 


If you configure an Intersite Transfer Service URL for an Identity Server that is the Access Manager 
Identity Server and the service provider is either another Identity Server or a third-party server, you 
can simplify the Intersite Transfer Service URL to the following format: 


<identity provider URL>?id=<user_definedID> 
For example: 
¢ SAML 2.0: https://test.blr.novell.com:8443/nidp/sam12/ 
idpsend?id=testsaml2&TARGET=https://eng.provo.novell.com 


¢ SAML 1.1: https://testsb.blr.novell.com:8443/nidp/saml1/ 
idpsend?id=testsaml&TARGET=https://eng.provo.novell.com 


¢ Liberty: https://testsb.blr.novell.com:8443/nidp/idff/ 
idpsend?id=libertytest&TARGET=https://eng.provo.novell.com 


If the Allow any target option is enabled and if the Intersite Transfer Service URL has a target value, 
then the user is redirected to target URL. 


The Intersite Transfer Service URL for SAML 2.0 will be https://testsb.blr.novell.com:8443/ 
nidp/sam12/idpsend?id=testsam12&TARGET=ht tp: //www. google.com where http:// 
www.google.com is the target URL. 
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3.9.10.2 


NOTE: Depending on the usage, the target parameter serves different purpose. It is case-sensitive. 


¢ target: Specifies the idpsend URL with a contract id. 
+ TARGET: Specifies URL of the final destination. 


Use case: If authentication with a particular contract is enabled in Intersite URL, you are redirected to 
the default target URL. Use the following format: http(s)://<$idp_host_name>/nidp/ 
app?id=<$contract_to_be_executed>&target=http(s)://<$idp_host_name>/nidp/sam12/ 
idpsend?id=<$saml_sp_identifier>. 


For more information, see How to access an Identity Server Intersite Transfer URL with a specific 
contract. 


NOTE: The contract_to_be_executed is executed by Identity Server and is case sensitive. 


For example, https://www. idp.com:8443/nidp/app?id=npbasic&target=https:// 
www. idp.com:8443/nidp/sam12/idpsend?id=serviceprovider1. 


How it works? 


In the above example, identity provider authentication is done with the contract id npbasic. You are 
now redirected to the service provider by using the saml_sp_identifier id (serviceprovider’). 
After authentication (if configured with persistent federation), the page redirects you to the available 
default target, or to the nidp login page of the service provider. 


For configuration and ID information, see “Configuring an Intersite Transfer Service Target for a 
Service Provider” on page 199. 


In the Intersite Transfer Service URL, id can be used for the following purposes: 
1. To simplify the intersite URL.<identity provider URL>?id=<user_defined|ID> 


2. To execute a particular contract in Identity Server login service with intersite URL. 


http(s)://<$idp_host_name>/nidp/ 
app?id=<$contract_to_be_executed>&target=http(s)://<$idp_host_name>/nidp/ 
sam12/idpsend?id=<$saml_sp_identifier> 


Specifying the Intersite Transfer Service URL for the Login URL 
Option 


Liberty and SAML 2.0 support a single sign-on URL. Because SAML 1.1 does not support a single 
sign-on URL, you need to specify the Intersite Transfer Service URL in the Login URL option on the 
authentication card for the SAML 1.1 identity provider: 


Figure 3-21 SAML 1.1 Authentication Card 


Configuration \ Metadata JU alr ere 


ID; | 


Text: idp-saml-206 | 


Login URL: https://jwilson.provo.novell.com:8443/nidp/saml/idpser 


Image: Customizable qj 


Show Card 
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For a card to appear as a login option, you must specify a Login URL and select the Show Card 


option. Figure 3-22 illustrates a possible configuration that requires the Intersite Transfer Service for 


the SAML 1.1 protocol. 


Figure 3-22 Federated Identity Configuration 


Identity Server Identity Server 
Site A Site B 
Identity Provider: A Identity Provider: B Access Gateway 
DNS: idp.sitea.novell.com Service Provider: 1 


DNS: idp.siteb.novell.com 


Web Server 


a 


URL: https://eng.provo.novell.com/myapp 


Service Provider: 2 
DNS: eng.provo.novell.com 


If you want a card to appear that allows the user to log in to Site A (as shown in Figure 3-21), you 
need to specify a value for the Login URL option. 


Using the DNS names from Figure 3-22, the complete value for the Login URL option is as follows: 


https://idp.sitea.novell.com:8443/nidp/saml/idpsend?PID=https:// 
idp.siteb.novell.com:8443/nidp/saml/metadata&TARGET=https:// 
idp.siteb.novell.com:8443/nidp/app 


The following happens when this link is invoked: 


1. The browser performs a Get to the identity provider (Site A). 


2. If the identity provider (Site A) trusts the service provider (Site B), the identity provider prompts 


the user for authentication information and builds an assertion. 


3. The identity provider (Site A) sends the user to the service provider (Site B), using the POST or 


Artifact method. 


4. The service provider (Site B) consumes the assertion and sends the user to the TARGET URL 


(the user portal on Site B). 


To configure the settings for the intersite transfer service, see “Modifying the Authentication Card for 


SAML 1.1” on page 508. 
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3.9.10.3 


Using Intersite Transfer Service Links on Web Pages 


The Intersite Transfer Service URL can be used on a web page that provides links to various 
protected resources requiring authentication with a specific identity provider and a specific protocol. 
Links on this web page are configured with the URL of the Intersite Transfer Service of the identity 
provider to be used for authentication. Clicking these links directs the user to the appropriate identity 
provider for authentication. Following successful authentication, the identity provider sends a SAML 
assertion to the service provider. The service provider uses the SAML assertion to verify 
authentication, and then redirects the user to the destination URL as specified in the TARGET portion 
of the Intersite Transfer Service URL. 


Below are sample links that might be included on a web page. These links demonstrate the use of 
SAML 1.1, SAML 2.0, and Liberty formats for the Intersite Transfer Service URL: 


SAML 1.1: <a href="https://idp.sitea.novell.com:8443/nidp/saml/idpsend?PID=https:// 
idp.siteb.novell.com:8443/nidp/saml/metadata&TARGET=https://eng.provo.novell.com/ 
samli/myapp">SAML1 example</a> 


SAML 2.0: <a href="https://idp.sitea.novell.com:8443/nidp/sam12/idpsend?PID=https:/ 
/idp.siteb.novell.com:8443/nidp/sam12/metadata&TARGET=https:// 
eng.provo.novell.com/sam12/myapp">SAML2 example</a> 


Liberty: <a href="https://idp.sitea.cit.novell.com:8443/nidp/idff/ 
idpsend?PID=https://idp.siteb.novell.com:8443/nidp/idff/metadata&TARGET=https:// 
eng.provo.novell.com/liberty/myapp">Liberty example</a> 


Figure 3-23 illustrates a network configuration that could use these sample links. 


Figure 3-23 Using the Intersite Transfer Service URL 


Identity Server Identity Server 
Site A Site B 
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Identity Provider: A 


DNS: idp.sitea.novell.com Identity Provider: B 
Service Provider: 1 
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Only Liberty Protocol 


Access Gateway 
Web Server 


URL: https://eng.provo.novell.com/myapp 


Service Provider: 2 
DNS: eng.provo.novell.com 


Third-Party Server 
Site Z 
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In this example, Site Z places links on its web page, using the Intersite Transfer Service URL of Site 
A. These links trigger authentication at Site A. If authentication is successful, Site A sends an 
assertion to Site B. Site B verifies the authentication and redirects the user to the myapp application 
that it is protecting. 
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3.9.10.4 


When defining the intersite transfer URL within Administration Console, you can define an id and 
target for the SAML service provider (SP) you are accessing. For more information about accessing 
an Identity Server intersite transfer URL with a specific contract, see TID 7005810. 


Configuring an Intersite Transfer Service Target for a Service 
Provider 
If you have created web pages that have links that specify a Intersite Transfer Service URL (see 


“Using Intersite Transfer Service Links on Web Pages” on page 198), you can have Identity Server 
control the TARGET parameter. 


1 Click Devices > Identity Servers > Edit > [Liberty, SAML1.1, or SAML 2.0] > [Service Provider] > 
Intersite Transfer Service. 

2 Fill in the following: 
ID: (Optional) Specify an alphanumeric value that identifies the target. 


If you specified an ID for the target, you can use this value to simplify the Intersite Transfer URL 
that must be configured at the service provider. This is the <user_definedID> value in the 
following format for the Intersite Transfer URL. 


<identity provider URL>?id=<user_definedID> 


The ID specified here allows Identity Server to find the service provider's metadata. 


Target: Specify the URL of the page that you want to display to users when they authenticate 
with an Intersite Transfer URL.The behavior of this option is influenced by the Allow any target 
option. NetIQ recommends you to specify a default target URL, for example, https:// 
www.serviceprovider1.com. 


Allow any target: You can either select or not select this option. 
+ When you select this option, 
¢ if the Intersite Transfer URL has a target value, then the user is sent to target url. 


+ if the Intersite Transfer URL does not have a target value, then the user is sent to the 
configured target, that is, www.serviceprovider1.com. 


+ When you do not select this option, 


+ if the Intersite Transfer URL has a target value, then the user is sent to the target 
www.serviceprovider1.com irrespective of the target mentioned in the Intersite Transfer 
URL. 


+ if the Intersite Transfer URL does not have a target value, the user is sent to 
www.serviceprovider1.com. 


3 Click OK twice. 
4 Update Identity Server. 
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3.9.10.5 


3.9.10.6 


Configuring Whitelist of Target URLs 


Redirection, which is required by many applications and services, inherently brings in a security risk. 
Redirects are dangerous because unsuspecting users who are visiting trusted sites can be redirected 
to malicious sites that exploit the users' trust. A new featured, called whitelist, has been added that 
restricts target URLs to specific domains. 


The whitelist feature allows you to restrict target URLs to URLs which match the domains in the 
whitelist. Any target URLs that use a domain that is not in the list are blocked and the user receives 
the following error message: The request to provide authentication to a service provider 
has failed (outsidedomain.com-89F57BF823DFE551). 


1 Click Devices > Identity Servers > Edit > [Liberty, SAML1.1, or SAML 2.0] > [Service Provider] > 
Intersite Transfer Service. 

2 In the Domain List, click New. 

3 Enter the domain name, then click OK. 


The domain name must be a full domain name, such as www.novell.com. Wildcard domain 
names, such as www. novell. * .com, do not work. 


4 To edit an existing domain name, click the name, modify the name, then click OK. 


5 To delete an existing domain name, select the check box by the domain, click Delete, then click 
OK to delete or Cancel to close the window. 


6 Click OK. 
7 Update Identity Server. 


Validating Incoming Authentication Request for Assertion 
Consumer Service URL 


When an authentication request from a service provider is not signed, Identity Provider cannot 
validate the authenticity and integrity of the request. So any malicious user who can intercept the 
request can change the Assertion Consumer Service URL in the request and make the Identity 
Provider to send the assertion to malicious sites. 


To secure and validate the authentication request from the service provider, you can use the following 
options in the service provider configuration of Identity provider: 


NOTE: These options must be defined to avoid security issues during an unsigned SAML 
Authentication Request. 


SAML2_ACS_URL_RESTRICT: This option ensures Identity Provider will validate the Assertion 
Consumer Service URL in the request against the trusted metadata URL before sending the 
assertion. So if the Assertion Consumer URL in the Authentication Request is tampered by any 
malicious user, Identity Provider terminates the request and assertion will not be sent. 


SAML2_ACS_DOMAIN_WHITELIST: This option ensures Identity Provider will validate the 
Assertion Consumer URL in the request against a white list of domains. If the Assertion Consumer 
Service URL is not matching with any of the domain URLs in the white list, request is terminated by 
the Identity Provider. 


You must define SAML2_ACS_ DOMAIN WHITELIST along with SAML_ACS_URL_RESTRICT for a 
service provider in Identity Provider because this option does not work if 
SAML_ACS_URL_RESTRICT is not enabled. 
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3.9.10.7 


3.9.10.8 


To define these options, perform the following in Administration Console: 


1 Click Devices > Identity Servers > IdP Cluster > SAML2. 


2 Select the required service provider from the Service Providers list. 
3 Click Options. 

4 Click New, then select OTHER from the drop down list. 

4a If you want Identity Provider to allow authentication only to the trusted ACS URLs, specify 


the following: 
Property Name: SAML2_ACS URL_RESTRICT 
Property Value: true 


4b If you want Identity Provider to perform additional validation of the authentication request 


with the ACS domain whitelist, specify the following: 
Property Name: SAML2_ACS_ DOMAIN_WHITELIST 


Property Value: Domain names separated with semi-colon(;) and no space. For example, 


www. airlines.com;www.example.com. 


Federation Entries Management 


Identity federation is the association of accounts between an identity provider and a service provider. 


Step up Authentication Example for an Identity Provider Initiated 
Single Sign-On Request 


Setup: Let us assume that: 


+ NetIQ Access Manager is acting as an identity provider. 


¢ The following three contracts in the identity provider are configured: 


+ name password basic contract with Authentication level as 10 
+ name password form contract with Authentication level as 20 
+ secure name password contract with Authentication level as 30 


NOTE: Enable the Satisfiable by a contract of equal or higher level option for contracts with 


authentication level 10 or 20 to avoid prompting for authentication when a user is already 


authenticated against the contract with level 30. 


+ The name password form contract for a service provider named SP_A is configured in the 


identity provider. 


For more information about creating and configuring the contracts, see Section 5.1.4, 
“Configuring Authentication Contracts,” on page 379. 


Configuration: Complete the following steps: 


1. 


In the NetIQ Identity Server, configure the service provider as a trusted provider. 


For more information, see Section 3.9.3, “Managing Trusted Providers,” on page 181. 


. Inthe service provider, configure the NetIQ Identity Server as a trusted provider. 


For more information, see Section 3.9.3, “Managing Trusted Providers,” on page 181. 


. In the NetlQ Identity Server, configure the service provider with the required authentication 


contracts. 
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For information about how to configure a service provider, see “Defining Options for SAML 2.0” on 
page 487, “To Define Options for Liberty Service Provider” on page 515 and“Defining Options for 
SAML 1.1 Service Provider” on page 508. 


Results: The following are the four possible scenarios: 


¢ Ifthe user was authenticated with the name password basic contract before making an Intersite 
Transfer Service request to SP_A, the identity provider will step up to the name password form 
authentication. 


+ Ifthe user was authenticated with the name password form contract before making an Intersite 
Transfer Service request to SP_A, the identity provider will not ask for the authentication. 


+ Ifthe user was authenticated with the secure name password contract before making an Intersite 
Transfer Service request to SP_A, the identity provider will not ask for the authentication. 


¢ Ifthe user is not authenticated while making an Intersite Transfer Service request to SP_A, the 
identity provider will step up to the name password form authentication. 


The following diagram illustrates the workflow: 


Identity Provide TE y 

Home Page Session consisting 
of authenticated 
contracts 


cee eee = > 


o 
° 


Workflow: 


User tries to authenticate in the identity provider. 
User is prompted to authentication using the Name Password Basic contract. 
User enters the credentials. 


Bh OU N FP 


The Name Password Basic contract is authenticated in the identity provider and added to the 
user session. 


The Name Password Basic contract is the default contract in the identity provider. 


ol 


User logs into the identity provider. 
6 User makes an Intersite Transfer Service request to SP_A. 
7 The identity provider prompts for the authentication using the Name Password Form contract. 
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8 User enters the credentials. 


9 The Name Password Form contract is authenticated in the identity provider and added to the 
user session. 


10 User is redirected to SP_A. 


NOTE: For information about service provider initiated single sign-on and its example, see “Contracts 
Assigned to a SAML 2.0 Service Provider” on page 477. 


3.9.10.9 URL Query String Parameters 


The following table lists query string parameters and their descriptions: 


Parameter Description 


id While defining the Intersite Transfer Service URL, you can define an id and target for 
the SAML service provider being accessed. 


For example, if you defined the id as testsaml and TARGET as URL of service provider, 
the login URL is https:// <identity provider server >:<port>/nidp/saml/ 
idpsend?id=testsaml&TARGET=<URL of service provider>. 


If TARGET is not specified, the login URL is https:// <identity provider server >:<port>/ 
nidp/saml/idpsend?id=testsaml. 


PID You can use this parameter when another provider is added and an Intersite Transfer 
Service id is not defined. 


For example, the login URL in this case can be https:// <identity provider 
server >:<port>/nidp/saml/idpsend?PID=<https://identity provider 
server>:8443/nidp/saml/metadata&TARGET=<URL of service provider>. 


target Specifies the idpsend URL with a contract ID. 


If authentication with a particular contract is enabled in the Intersite Transfer Service 
URL, you are redirected to the default target URL. 


Use the following format: http(s)://<$idp_host_name>/nidp/ 
app?id=<$contract_to_be_executed>&target=http(s)://<$idp_host_name>/nidp/saml2/ 
idpsend?id=<$saml_sp_identifier>. 


For example, https: //www.idp.com:8443/nidp/ 
app?id=npbasic&target=https://www. idp.com:8443/nidp/sam12/ 
idpsend?id=serviceprovider1. 


TARGET Specifies URL of the final destination. Format of the URL: <identity provider 
URL>?PID=<entityID>& TARGET=<final_destination_URL> 


For example, https://<identity provider url/nidp/saml2/ 
idpsend?id=testsaml2&TARGET=ht tp: //www. google.com. Here http: // 
www.google.com is the destination. 
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3.10 


3.10.1 


3.10.1.1 


Configuring Single Sign-On to Specific 
Applications 


You can configure single sign-on through Access Gateway and through federation protocols. This 
section discusses how to configure single sign-on for specific applications through Access Gateway. 


For more information about how to configure single sign-on through federation, see Section 5.2, 
“Federated Authentication,” on page 428. 


¢ Section 3.10.1, “Configuring Protected Resource for a SharePoint Server,” on page 204 


¢ Section 3.10.2, “Configuring a Protected Resource for a SharePoint Server with an ADFS 
Server,” on page 210 


¢ Section 3.10.3, “Configuring a Protected Resource for Outlook Web Access,” on page 213 
¢ Section 3.10.4, “Configuring a Protected Resource for a Novell Vibe 3.3 Server,” on page 216 
¢ Section 3.10.5, “Configuring Access to the Filr Site through Access Manager,” on page 220 


Configuring Protected Resource for a SharePoint Server 


You can protect a SharePoint server as a domain-based or a path-based multi-homing resource on 
Access Gateway. When you protect a SharePoint server on Access Gateway, you might see issues 
with rewriting if the published DNS name is not the same as the DNS name of the original server. 
Also, if you access SharePoint folder by using non-browser clients such as Microsoft Network Place, 
Nautilus in SUSE Linux Enterprise Server (SLES), or the MAC finder, you might see issues because 
these WebDAV clients do not support 302 redirection for authentication. You must modify the 
authentication procedure to prevent redirection on initial authentication or redirection to Identity 
Server when the user session expires. 


¢ Section 3.10.1.1, “Protecting SharePoint Using the Domain-Based Multi-Homing Proxy Service,” 
on page 204 


¢ Section 3.10.1.2, “Protecting SharePoint for the Path-Based Multi-Homing Proxy Service,” on 
page 206 


¢ Section 3.10.1.3, “Authorizing Access to SharePoint Files,” on page 209 


NOTE: These configuration steps are verified for SharePoint 2010. 


Protecting SharePoint Using the Domain-Based Multi-Homing Proxy 
Service 

You can configure Access Manager to provide protected access to SharePoint by using a domain- 
based proxy service and single sign-on access by using identity injection. You can access SharePoint 


with a URL similar to this: https://<Published DNS name>:<port number if any>/path. For example, 
https://shpt.multibox-mag.com/default.aspx. 


Perform the following configurations: 


1 Configure the proxy service type as Domain-Based Multi-Homing. 
For example, the published DNS Name = shpt.multibox-mag.com. 


For more information, see “Configuring the Domain-Based Proxy Service” on page 217. 
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2 Configure the following Web servers options: 
+ Web Server Host Name: Specify the actual host name of the SharePoint server. 
+ Connect Port: Specify the port that Access Gateway should use to communicate 
with Web servers. 


For more information, see Section 3.8.3, “Configuring Web Servers of a Proxy Service,” on 
page 126. 


3 Create new HTML Rewriter profiles: one Word profile and one Character profile. 


For more information about how to create a new rewriter profile, “Creating or Modifying a 
Rewriter Profile” on page 153. 


+ Create a Word rewriter and enter the following values: 
And Document Content-Type Header is: click New, then specify the following type: 


application/x-vermeer -rpc 

Variable or Attribute Name to Search for Is: Create the following two new attributes: 
formvalue 

value 


+ Create a Character rewriter. In the Additional Strings to Replace section, specify the 
search and replace strings as shown in Table 3-1 on page 205, then click OK. 


NOTE: win2k8-r2-64bit:32274 in tables Table 3-1 and Table 3-2 is referring to SharePoint 
server's domain name and the port in which it is configured. Change it with your SharePoint 
server's domain name and the port number. 


Table 3-1 Search and Replace strings 


Search String Replace String 


\u0022http:\u002f\u002fwin2k8-r2-64bit:32274 \u0022https://shpt.multibox-mag.com 


http%253A%252F %252Fwin2k8-r2- https://shpt.multibox-mag.com 
64bit%253A32274 

http%3A%2F %2Fwin2k8-r2- https%3A%2F%2Fshpt.multibox-mag.com 
64bit%2Ecom%3A32274 

http%3a%2f%2fwin2k8-r2-64bit%3a32274 https://shpt.multibox-mag.com 

http:%2f% 2fwin2k8-r2-64bit https://shpt.multibox-mag.com 
http:\u00252F\u00252Fwin2k8-r2-64bit https://shpt.multibox-mag.com 
http\u00253A\u00252F\u00252Fwin2k8-r2- https://shpt.multibox-mag.com 
64bit\u00253A32274 


Save and enable this rewriter profile and move it to the top of the ordered list of profiles for 
this accelerator. 


4 Configure the protected resources: pr-private, pr-public, and pr-other. 
For more information, see Section 3.8.4, “Configuring Protected Resources,” on page 128. 
+ Protected resource: pr-private 


+ Authentication Procedure: Secure Name/Password — Form type contract 
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+ URL Path: /default.aspx 


¢ Identity Injection: Enabled (injects Credential Profile LDAP name and password into 
the Authorization headers) 


+ Protected resource: pr-public 
+ Authentication Procedure: None 
¢ URL Path: / 
+ Protected resource: pr-other 
+ Authentication Procedure: WebDAV 
Create a new authentication procedure with the following settings: 
Contract: Secure Name/Password - Form 
Non-Redirected Login: enabled 


Realm: Specify the name of the realm. Ensure that the value is same as the value of 
the SharePoint IIS Basic Authentication Setting. 


For example: If you have specified the value of Basic Authentication Setting value as 
xyz, enter the same value as the name of the realm. 


Redirect to Identity Server When No Authentication Header is Provided: disabled 
¢ URL Path: /* 


¢ Identity Injection: Enabled (injects Credential Profile LDAP name and password into 
the Authorization headers) 


Protecting SharePoint for the Path-Based Multi-Homing Proxy 
Service 

You can configure Access Manager to provide protected access to SharePoint using a path-based 
proxy service with the Remove Path on Fill option enabled, and single sign-on access by using 


identity injection. You can access SharePoint with a URL similar to this: https://<Published DNS 
name>:<port number if any>/path. For example, https://multibox-mag.com/shpt/default. aspx. 


When the Remove Path on Fill option is enabled, SharePoint access requires the following additional 
entries in the Advanced Options section for Global, Master and path-based service. 


Advanced options required in the global settings include: 
+ NAGGlobalOptions AllowMSWebDavMiniRedir=on 
Advanced options required in the master service include: 
+ NAGHostOptions primaryWebdav=/shpt 
+ NAGHostOptions webdavPath=/_vti_inf.html 
+ NAGHostOptions webdavPath=/_vti_bin/_vti_aut/author.dll 
+ NAGHostOptions webdavPath=/_vti_bin/shtml.dll/_vti_rpc 
+ NAGHostOptions webdavPath=/_vti_bin/_vti_aut/author.dll 
+ NAGHostOptions webdavPath=/_vti_bin/_vti_adm/admin.dll 
+ NAGHostOptions webdavPath=/_vti_bin/owssvr.dll 


Advanced options required in the path-based service include: 


+ NAGChildOptions WebDav=/shpt 
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Perform the following configurations: 
1 Configure the proxy service type as Path-Based Multi-Homing. For example, Published DNS 
Name= shpt.multibox-mag.com) 
+ Path List: /shpt 
Remove Path on Fill: Select the check box. 
Reinsert Path in “set-cookie” Header: Select the check box. 
For more information, see “Configuring a Path-Based Multi-Homing Proxy Service” on page 168. 
2 Configure the following options for web servers: 
+ Web Server Host Name: Enter the actual host name of the SharePoint server. 


+ Connect Port: Enter the port that Access Gateway should use to communicate with the 
Web servers. 


For more information, see Section 3.8.3, “Configuring Web Servers of a Proxy Service,” on 
page 126. 


3 Create new HTML Rewriter profiles: one Word profile and one Character profile. 


For more information about how to create a new rewriter profile, see Section 3.8.5.5, “Creating 
or Modifying a Rewriter Profile,” on page 153. 


+ Create a Word rewriter. Keep the default values except the following: 
And Document Content-Type Header Is: click New, then specify the following type: 


application/x-vermeer -rpc 


Rewrite Inbound Query String Data: Select the check box. 

Rewrite Inbound POST Data: Select the check box. 

Rewrite Inbound Headers: Select the check box. 

Enable Rewriter Actions: Select the check box. 

Variable or Attribute Name to Search for Is: Specify the following attributes: 


ctx.displayFormur1l 
ctx.editFormUrl 
ctx.HttpPath 
ctx.imagesPath 
ctx.listUrlDir 
editPrmsurl 
formvalue 
L_Menu_BaseUrl 
sDialoguUrl 
strHelpuUrl 
strImageAZ 
strImagePath 

value 

webUrl 

WPSC .WebPartPage.WebServerRelativeURL 


Java Script Method of Search for is: Specify the following attributes: 


insertitem 
ProcessDefaultNavigateHierarchy 
UpdateFormDigest 


String to Search for is: Specify the following attributes: 
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Search=/_layouts/images 
Replace=$path/_layouts/images 
Search=/sites 

Replace=$path/sites 
Search=\u002f_layouts\u002fimages 


Replace=$path\u002f_layouts\u002fimages 


¢ Create a Character rewriter and enter the following values:. 


And Document Content-Type Header Is: application/x-vermeer-rpc 


Additional Strings to Replace: Specify the search and replace strings as shown in Table 


3-2, then click OK. 


Table 3-2 Search and Replace strings 


Search String 


\u0022http:\u002AU002fwin2k8-r2-64bit:32274 
\u002f_layouts 

\u002f_vti_bin 

event,’/_ layouts 


http%253A%252F %252Fwin2k8-r2- 
64bit%253A32274 


http%3A%2F %2Fwin2k8-r2- 
64bit%2Ecom%3A32274 


http%3a%2f%2fwin2k8-r2-64bit%3a32274 
http:%2f% 2fwin2k8-r2-64bit 
http:\u00252F\u00252Fwin2k8-r2-64bit 


http\u00253A\u00252F\u00252Fwin2k8-r2- 
64bit\u00253A32274 


Replace String 


\u0022https://multibox-mag.com/shpt 
/shpt\u002f_layouts 
/shpt\u002f_vti_bin 
event,'/shpt/_layouts 


https://multibox-mag.com/shpt 


https%3A%2F%2Fmultibox-mag.com/shpt 


https%3a%2f%2fmultibox-mag.com/shpt 
https://multibox-magcom/shpt 
https://multibox-mag.com/shpt 
https://multibox-mag.com/shpt 

webUrl=/ webUrl=/shpt 


Save and enable this rewriter profile and move it to the top of the ordered list of profiles for 


this accelerator. 


4 Configure the protected resources: pr-private, pr-public, and pr-other. 


For more information, see Section 3.8.4, “Configuring Protected Resources,” on page 128. 


+ Protected resource: pr-private 


+ Authentication Procedure: Secure Name/Password — Form type contract 


+ URL Path: /shpt/default.aspx 


¢ Identity Injection: Enabled (injects Credential Profile LDAP name and password into 


the Authorization headers) 
+ Protected resource: pr-public 
+ Authentication Procedure: None 
¢ URL Path: /shpt 
+ Protected resource: pr-other 


+ Authentication Procedure: WebDAV 
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Create an authentication procedure with the following settings: 

Contract: Secure Name/Password - Form 

Non-Redirected Login: enabled 

Realm: Sharepoint 

Redirect to Identity Server When No Authentication Header is Provided: disabled 
¢ URL Path: /shpt/* 


¢ Identity Injection: Enabled (injects Credential Profile LDAP name and password into 
the Authorization headers) 


Authorizing Access to SharePoint Files 


A user can view the files on a SharePoint server after authenticating at Identity Server. However, to 
authorize access to open or edit any file, you must perform the following steps by using Access 
Gateway: 


1 Set the NAGGlobalOptionsAllowMSWebDavMiniRedir advanced Access Gateway option to on. 


2 Add the Access manager SharePoint domain to the browser’s trusted site, and add the 
certificates to the Trusted Root Certification Authorities. 


3 Add the following line to the httpd.conf available at /etc/opt/novell/apache2/conf/ file. 
LoadModule headers_module libexec/mod_headers.so 
4 Add following entries to httpd.conf file: 


<LocationMatch ".*\.doc$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.docx$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.xls$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.xlsx$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.ppt$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.pptx$"> 

Header set Content-Disposition attachment 
</LocationMatch> 


5 Restart novell-apache2 services. 


NOTE: If the preceding steps do not work for other versions of SharePoint, then use WS-Federation 
protocol to federate SharePoint with Identity Server. For more information about using WS- 
Federation, see Section 5.2.8, “Configuring WS Federation,” on page 535. 
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3.10.2 


3.10.2.1 


Configuring a Protected Resource for a SharePoint Server 
with an ADFS Server 


If your SharePoint server is configured to use an ADFS server and you want to create a protected 
resource for the SharePoint server, you need to configure the following Access Manager features. 
The instructions assume that you have a functioning SharePoint server and a functioning Access 
Manager system: 

¢ Section 3.10.2.1, “Configuring a Custom Contract,” on page 210 

¢ Section 3.10.2.2, “Creating a Reverse Proxy Service,” on page 211 


¢ Section 3.10.2.3, “Configuring Multiple Protected Resources,” on page 211 


Configuring a Custom Contract 


ADFS requires a different format for a contract URI than the format used in the default contracts. It 
expects the URI to conform to the format of a URL. You need to create a custom contract. 
1 Click Devices > Identity Servers > Servers > Edit > Local > Contracts 
2 Click New, then fill in the following fields: 
Display name: Specifies the name of the authentication contract. 
URI: Specifies a value that uniquely identifies the contract from all other contracts. No spaces 
can exist in the URI field. For SharePoint, specify the following format for the URI: 


https: //<baseurl>/name/password/uri 


Replace <baseur!l> with the base URL of your Identity Server. If the DNS name of your Identity 
Server is idp-50.amlab.net, the URI would have the following format: 


https://idp-50.amlab.net :8443/nidp/name/password/uri 
Methods and Available Methods: Move a name/password method to the Methods list. We 
recommend Secure Name/Password - Basic, but you can use Name/Password - Basic. 


Do not configure a password expiration servlet. This contract is going to be used with non- 
redirected login, which prevents all redirection, including redirection to a password expiration 
service. 


For more information about other options, see Section 5.1.4, “Configuring Authentication 
Contracts,” on page 379. 


3 Click Next. 
4 Configure a card for the contract by filling in the following: 
Text: Specify the text that is displayed on the card to the user. 


Image: Specify the image to be displayed on the card. To use an existing image, select an image 
from the drop-down list. To add an image to the list, click Select local image. 


Show Card: Determine whether the card is shown to the user, which allows the user to select 
and use the card for authentication. If this option is not selected, the card is only used when a 
service provider makes a request for the card. 


5 Click Finish, then OK. 
6 Update Identity Server and Access Gateway. 
7 Continue with “Creating a Reverse Proxy Service” on page 211. 
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3.10.2.3 


Creating a Reverse Proxy Service 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 
2 In the Proxy Service List section, click New. 
3 Fill in the following fields: 


Proxy Service Name: Specify a display name for the proxy service that Administration Console 
uses for its interfaces. 


Multi-Homing Type: Select Domain-Based as the multi-homing method that Access Gateway 
must use to identify this proxy service. 


Published DNS Name: Specify the DNS name you want the public to use to access the 
SharePoint server. This DNS name must resolve to the IP address you set up as the listening 
address. 


If the DNS name of the reverse proxy is the same as the DNS name of the SharePoint server, no 
rewriting configuration is required. If they are different, there is a high probability that the 
application will respond incorrectly to user requests. 


Web Server IP Address: Specify the IP address of the IIS Web server with the SharePoint 
server. 


Host Header: Select the Web Server Host Name option. 


Web Server Host Name: Specify the DNS name of the SharePoint server that Access Gateway 
must forward to the web server. 


For more information about how to create a reverse proxy, see Section 3.8.2, “Managing 
Reverse Proxies and Authentication,” on page 119 


4 Click OK. 
5 Continue with “Configuring Multiple Protected Resources” on page 211. 


Configuring Multiple Protected Resources 


If your SharePoint server has been configured for multiple domains, you need to create three 
protected resources to enable single sign-on. The server has two ways to access the home page. 
You need to create a protected resource for each of these paths, and then a protected resource for 
the other pages. These protected resources must have a configuration similar to the following: 


SharePoint Page URL Path Contract Authentication Procedure 
home page default.aspx custom Normal 

root / custom Normal 

all others [> custom Non-redirected login 


For single sign-on, all the protected resources need to specify the same contract. When assigning the 
contract for the /* resource, the contract needs to be configured to use non-redirected login for its 
authentication procedure. When a user first accesses the SharePoint server, the users are directed 
either to the home page or the root of the server. From either of these locations, the users can be 
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redirected to Identity Server for authentication. After the users have authenticated and the SharePoint 
server requests authentication for access to any of the other pages, these pages need to be 
configured to use non-redirected login. 


1 


6 
7 


In the Proxy Service List, click the name of the Proxy Service you created, then click Protected 
Resources. 


To create a protected resource for the home page: 


2a In the Protected Resource List, click New, specify a name such as homepage, then click 
OK. 


2b For the home page of the SharePoint server, specify the following values: 
Authentication Procedure: Select the custom contract you created. 
URL Path: Click /* and replace it with default.aspx, then click OK twice. 

To create a protected resource for the root page: 

3a In the Protected Resource List, click New, specify a name such as root, then click OK. 

3b For the root of the SharePoint server, specify the following values: 
Authentication Procedure: Select the custom contract you created. 
URL Path: Click /* and remove the asterisk, then click OK twice. 

To create a protected resource for all other pages: 


4a In the Protected Resource List, click New, specify a name such as allothers, then click 
OK. 


4b For all other pages of the SharePoint server, specify the following values: 
Authentication Procedure: Select the custom contract you created. 
URL Path: Leave the default value. 
4c Click the Edit Authentication Procedures icon on the Authentication Procedure line. 
4d Click the name of your custom contract, then fill in the following: 
Non-Redirected Login: Select this option. 


Realm: Specify a name that your users associate with the SharePoint server. This name is 
displayed when the user needs to reauthenticate. 


For more information about this feature, see “Configuring an Authentication Procedure for 
Non-Redirected Login” on page 132. 


Click OK three times. 


In the Protected Resource List, you must have three protected resources that use the same 
Authentication Procedure. 


For information about configuring protected resources, see “Setting Up a Protected Resource” 
on page 129. 


Click Access Gateways, then update Access Gateway. 

(Conditional) If you have limited your users to one session, modify this limitation: 
7a Click Devices > Identity Servers > Edit. 
7b Increase the value of the Limit user sessions option. 
7c Click OK, then update Identity Server. 
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3.10.3 Configuring a Protected Resource for Outlook Web Access 


If you want to protect your Outlook Web Access server with Access Gateway, you need to configure 
the following Access Manager features. The instructions assume that you have a functioning Outlook 
Web Access server and a functioning Access Manager system: 

¢ Section 3.10.3.1, “Configuring a Protected Resource for Outlook Web Access,” on page 213 

¢ Section 3.10.3.2, “Configuring an Authentication Procedure,” on page 213 

¢ Section 3.10.3.3, “Configuring a Rewriter Profile,” on page 214 

¢ Section 3.10.3.4, “Configuring Identity Injection,” on page 215 

¢ Section 3.10.3.5, “Configuring Form Fill,” on page 215 


3.10.3.1 Configuring a Protected Resource for Outlook Web Access 


The following instructions assume that you have a basic setup with at least one reverse proxy and 
proxy service. If you don’t have this basic setup, see Section 3.8.2, “Managing Reverse Proxies and 
Authentication,” on page 119 and complete a basic setup before continuing. 

1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 

2 Inthe Proxy Service List section, click New. 

3 Specify a name for the proxy service, then click OK. 

4 Click the newly added proxy service. Fill in the fields: 


Proxy Service Name: Specify a display name for the proxy service, which Administration 
Console uses for its interfaces. 


Published DNS Name: Specify the DNS name you want the public to use to access your site. 
This DNS name must resolve to the IP address you set up as the listening address. 


Multi-Homing Type: Select the multi-homing method that Access Gateway must use to identify 
this proxy service. 


Web Server IP Address: Specify the IP address of the IIS web server. 
Host Header: Select the Web Server Host Name option. 


Web Server Host Name: Specify the DNS name of the Outlook Web Access server that Access 
Gateway must forward to the web server. 


5 Click OK. 


6 Continue with “Configuring an Authentication Procedure” on page 213. 


3.10.3.2 Configuring an Authentication Procedure 


1 Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > 
Protected Resources. 


2 Click New, then specify a display name for the resource. 


3 (Optional) Specify a description for the protected resource. You can use it to briefly describe the 
purpose for protecting this resource. 


4 Select an authentication contract. If you want to enable non-redirected login, select Name/ 
Password - Basic as the authentication contract. 


5 (Optional) If you want to enable non-redirected login, click the Edit Authentication Procedure 
icon, then click the contract that you have added to specify the following information: 


Non-Redirected Login: Select the option to enable non-redirected login. 
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Realm: Specify the security realm configured for the IIS server running the Outlook Web Access 
server. 


To check the security realm configured for the IIS server, open the IIS Administration Console, 
right-click the Outlook Web Access Server Access Gateway is protecting, then select Properties. 
The Directory Security tab contains the Security realm field. 


6 Create protected resource: 


6a 
6b 


In the Protected Resource List, click New, specify a name such as root, then click OK. 
Specify the following values: 
Authentication Procedure: Select the contract you created. 


URL Path: Make sure that /* is selected. If you have configured Outlook Web Access as a 
path-based service, then click the URL path and add the path name of the service. For 
example, /owa/*, where owa is the path name. 


Click OK twice. 


7 Create a second protected resource: 


7a 
7b 


In the Protected Resource List, click New, specify a unique name, then click OK. 
Specify the following values: 


Authentication Procedure: Do not select any authentication procedure because the URL 
path is a public resource. 


URL Path: Specify /exchweb/* in the URL path. If you have configured Outlook Web 
Access as a path-based service, click the URL path and add the path name of the service. 
For example, /owa/exchweb/*, where owa is the path name. 


Click OK twice. 


8 Click OK. 
9 In the Protected Resource List, ensure that the protected resource you created is enabled. 


10 If you want to enable single sign-on, then configure Identity Injection or Form Fill policy, 
depending on the Outlook Web Access configuration. For more information, see “Configuring 
Identity Injection” on page 215. 


11 Continue with “Configuring a Rewriter Profile” on page 214. 


3.10.3.3 Configuring a Rewriter Profile 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> HTML Rewriting. 


2 Click New in the HTML Rewriter Profile List. 


3 Configure a Word profile: 


3a 
3b 
3c 
3d 
3e 
3f 
3g 


Specify a name for the profile, select Word as the search boundary, then click OK. 

Click New in the Variable or Attribute Name to Search for Is section, then specify value. 
Click OK. 

Select Rewrite Inbound Query String Data. 

Select Rewrite Inbound Post Data. 

Select Rewrite Inbound Headers. 


Ensure that Enable Rewrite Actions remains selected. 
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3.10.3.4 


3.10.3.5 


4 (Optional) If you have configured the path-based multi-homing service, do the following: 


4a Add the following content types for the And Document Content-Type Header Is option in the 
Word profile: 


+ text/x-component 
¢ extension/htc 
4b Configure the following options for Strings to Search for Is: 
¢ Specify Search as /exchange and Replace With as $path/exchange 
¢ Specify Search as /exchweb and Replace With as $path/exchweb 
5 To save your changes to browser cache, click OK. 
6 Use the up-arrow button to move your profile to the top of the HTML Rewriter Profile List. 
7 To apply your changes, click the Access Gateways link, then click Update > OK. 


Configuring Identity Injection 


You must configure an Identity Injection policy to enable single sign-on with the Outlook Web Access 
server that has basic authentication configured. This Identity Injection policy must be configured to 
inject an authentication header. For information about creating this policy, see Section 8.4.3, 
“Configuring an Authentication Header Policy,” on page 813. 


Configuring Form Fill 


You can configure a Form Fill policy to prepopulate fields in the form when you log into the Outlook 
Web Access first time and then save the information in the completed form to the config store for 
subsequent logins. For information about how to create this policy, see Chapter 8.5, “Form Fill 
Policies,” on page 831. 


Enabling the Auto Submit option requires additional entries apart from the username and password 
fields. To enable the Auto Submit option: 


1 Click Policies > Policies > <Policy Name>. 


2 Inthe Edit Policy page, add the following details under Fill Options: 


Input Field Name Input Field Type Input Field Value Data Conversion 


destination Hidden String Constant : http:// None 
<webserver DNS Name/ 
owa> (when Web server is 
configured for http.) 


String Constant : https:// 
<webserver DNS Name/ 
owa> (when Web server is 
configured for https.) 


flags Hidden String Constant : 0 None 
forcedownlevel Hidden String Constant : 0 None 
isUt8 Hidden String Constant : 1 None 
trusted Radio Button String Constant : 0 None 
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3.10.4.1 


3 Under the Submit Options section, select the Enable JavaScript Handling check box. 
4 Enter document .cookie="PBack=0; path=/" in the Statements to Execute on Submit field. 
5 Click OK and apply the changes. 


Configuring a Protected Resource for a Novell Vibe 3.3 
Server 


The following sections explain how to configure Access Gateway with a domain-base multi-homing 
service. The instructions assume that you have a functioning Novell Vibe 3.3 server on Linux and a 
functioning Access Manager system with a reverse proxy configured for SSL communication between 
the browsers and Access Gateway. 


The Novell Vibe server needs to be configured to trust Access Gateway to allow single sign-on with 
Identity Injection and to provide simultaneous logout. You also need to create an Access Gateway 
proxy service and configure it. 

¢ Section 3.10.4.1, “Configuring the Novell Vibe Server to Trust Access Gateway,” on page 216 


¢ Section 3.10.4.2, “Configuring a Domain-Based Multi-Homing Service for Novell Vibe,” on 
page 217 


¢ Section 3.10.4.3, “Creating a Pin List,” on page 220 


For information about other possible Access Gateway configurations, see “Teaming 2.0: Integrating 
with Linux Access Gateway”. 


Configuring the Novell Vibe Server to Trust Access Gateway 


To use Novell Vibe as a protected resource of an Access Gateway and to use Identity Injection for 
single sign-on, the Teaming server needs a trusted relationship with Access Gateway. With a trusted 
relationship, the Teaming server can process the authorization header credentials. The Teaming 
server accepts only a simple username (such as user1) and password in the authorization header. 


This section explains how to set up the trusted relationship and how to enable simultaneous logout, 
so that when the user logs out of Teaming, the user is also logged out of Access Gateway. 


To configure the trusted relationship: 


1 Log in to the Novell Vibe server. 

2 Stop the Teaming server with the following command: 

/etc/init.d/teaming stop 

Run the installer -teaming.1inux script. 

Follow the prompts, then select Reconfigure settings. 
Follow the prompts, then select Advanced installation. 


oun fF O 


Follow the prompts, selecting the defaults until the Enable Access Gateway option appears, then 
type Yes. 


7 Inthe Access Gateway address(es) section, include the IP address of Access Gateway that is 
used for the connection to the Teaming server. 


If Access Gateway is part of a cluster, add the IP address for each cluster member. Wildcards 
such as 164.99.*.* are allowed. 


216 Setting Up a Basic Access Manager Configuration 


3.10.4.2 


When you specify IP addresses in this option, Novell Vibe logins are allowed only from the 
specified addresses. Also, if authorization header credentials are not present or are incorrect, 
the user is prompted for login by using Basic Authentication. 


8 When prompted for the Logout URL, specify the URL of the published DNS name of the proxy 
service plus /AGLogout. 


For example, if the published DNS name of the proxy service is vibe. doc. provo.novell.com, 
specify the following URL: 
https://Vibe.doc.provo.novell.com/AGLogout 


9 When you are prompted to use Access Gateway for WebDAV connections, specify No. 
10 Follow the prompts to complete the reconfiguration process. 
11 Start the Vibe server with the following command: 
/etc/init.d/teaming start 


12 Continue with “Configuring a Domain-Based Multi-Homing Service for Novell Vibe” on page 217. 


Configuring a Domain-Based Multi-Homing Service for Novell Vibe 


The following instructions describe how to set up a domain-based service to protect the Novell Vibe 
server. In this example, the published DNS name of the service is Vibe.doc.provo.novell.com. 
Users would access the Vibe server with a URL similar to http://Vibe.doc.provo.novell.com. 


To configure a domain-based service for Vibe, complete the following tasks: 


+ “Configuring the Domain-Based Proxy Service” on page 217 
¢ “Configuring Protected Resources” on page 218 


¢ “Configuring a Rewriter Profile” on page 219 


Configuring the Domain-Based Proxy Service 


You must create a new reverse proxy before you configure the domain-based proxy service. 
Configure the Vibe domain as the primary proxy service and enable SSL between browser and 
Access Gateway. For more information about how to create a new reverse proxy, see “Creating a 
Proxy Service” on page 121. 

1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 

2 In the Reverse Proxy List, click New, then specify the following details: 


Proxy Service Name: Specify a display name for the proxy service that Administration Console 
uses for its interfaces. 


Multi-Homing Type: Select Domain-Based. 


Published DNS Name: Specify the DNS name you want the public to use to access your site. 
This DNS name must resolve to the IP address you set up as the listening address. For 
example, vibe.doc.provo.novell.com. 


Web Server IP Address: Specify the IP address of the Vibe server. 
Host Header: Select the Forward Received Host Name option. 
Web Server Host Name: Specify the DNS name of the Vibe server. 
3 Click OK. 
4 Click the newly added proxy service, then select the Web Servers tab. 
5 Change the Connect Port to 8080. 
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If the Novell Vibe server has port forwarding enabled, you do not need to change from the default 
port 80. 


6 Click TCP Connect Options. 

7 Change the value of Data Read Timeout option to 300 seconds. 
This longer timeout is needed for file uploads. 

8 Click OK. 

9 Continue with “Configuring Protected Resources” on page 218. 


Configuring Protected Resources 


You must configure an Identity Injection policy to enable single sign-on with the Novell Vibe server. 
This Identity Injection policy must be configured to inject the authentication credentials into the 
authorization headers. 

1 Click Policies > Policies. 

2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type, then click 
OK. 


4 (Optional) Specify a description for the injection policy. This is useful if you plan to create multiple 
policies to be used by multiple resources. 


5 Inthe Actions section, click New, then select Inject into Authentication Header. 
6 Fill in the following fields: 
User Name: Select Credential Profile > LDAP User Name. 
Password: Select Credential Profile > LDAP Password. 
7 Click OK twice. 
8 Click Apply Changes. 


For more information about how to create such a policy, see Section 8.4.3, “Configuring an 
Authentication Header Policy,” on page 813. 


Assign this policy to the protected resources. You need to create two protected resources, one 
for HTML content and one for WebDAV and AJAX content. 


9 Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > 
Protected Resources. 


10 Create a protected resource for HTML content: 
10a In the Protected Resource List, click New, specify a name, then click OK. 


10b (Optional) Specify a description for the protected resource. You can use it to briefly describe 
the purpose for protecting this resource. 


10c Specify a value for Authentication Procedure. For example, select the Secure Namel 
Password - Form contract. 


10d In the URL Path List, remove the /* path and add the following two paths: 
/teaming/* 
/ssf/* 

10e Click OK. 
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11 Create a protected resource for WebDAV and AJAX content: 
11a In the Protected Resource List, click New, specify a unique name, then click OK. 


11b (Optional) Specify a description for the protected resource. You can use it to briefly describe 
the purpose for protecting this resource. 


114c Click the Edit Authentication Procedure icon. 
11d In Authentication Procedure List, click New, specify a name, then click OK. 
11e Specify details in the following fields: 


Contract: Select the Secure Name/Password - Form contract, which is same contract that 
you selected for the HTML content protected resource. 


Non-Redirected Login: Select this option. 


Realm: Specify a name that you want to use for the Teaming server. This name does not 
correspond to a Vibe configuration option. It appears when the user is prompted for 
credentials. 


Redirect to Identity Server When No Authentication Header is Provided: Deselect this 
option. 


11f Click OK twice. 
11g For the Authentication Procedure, select the procedure you just created. 
11h In the URL Path List, remove the /* path and add the following paths: 


= 


/ssfs/* 
/ssf/rss/* 
/ssf/atom/* 
/ssf/ical/* 
/ssf/ws/* 
/ssr/* 
/rest/* 


The /ssfs/* path is for WebDAV content and the /ssf/rss/* path enables non- 
redirected login for RSS reader connections. 


11i Click OK. 
12 In the Protected Resource List, ensure that the protected resources you created are enabled. 
13 To apply your changes, click Devices > Access Gateways, then click Update. 
14 Continue with “Configuring a Rewriter Profile” on page 214. 


Configuring a Rewriter Profile 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> HTML Rewriting. 


2 In HTML Rewriter Profile List, click New. 
3 Specify a name for the profile, select Word as the search boundary, then click OK. 
4 Inthe And Document Content-Type Header Is section, click New, then specify the following type: 


application/rss+xml 


5 In the Variable or Attribute Name to Search for Is section, click New, then specify the following 
as the variable to search for: 


value 


6 Click OK. 
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3.10.4.3 


3.10.5 


3.11 


7 Ensure that Enable Rewrite Actions remains selected. 
8 Click OK. 


9 In HTML Rewriter Profile List, move the Word profile you created to be the first profile in the list, 
and move the default profile to be the second profile in the list. 


10 Click OK. 
11 To apply your changes, click Devices > Access Gateways, Update. 
12 Continue with “Creating a Pin List” on page 220. 


NOTE: If Vibe is configured to send the binary content in the JSON format, you must disable the 
HTML Rewriter to prevent errors. 


Creating a Pin List 
Configure Access Gateway to bypass the published URL of the proxy service: 


1 Click Devices > Access Gateways > Edit. 
2 Click Pin List in the configuration page. 


3 Click New, then specify the published DNS name of the proxy service. For example, 
vibe.doc.provo.novell.com. 


4 Select Bypass as the Pin type. 
5 Click OK. 
6 To save the configuration changes, click Devices > Access Gateways, then click Update. 


NOTE: If you do not want Access Manager to cache site information, do not create a Pin List. 
Instead, you must configure Access Manager to forward cache control headers to the browser. This is 
the recommended configuration for Novell Vibe. For information about how to forward cache control 
headers to the browser, see Section 4.3.2, “Controlling Browser Caching,” on page 333. 


Configuring Access to the Filr Site through Access Manager 


For information about using Access Manager to configure a protected resource for a Novell Filr 
server, see Allowing Access Manager to configure a protected resource for a Novell Filr server (http:/ 
/www.novell.com/documentation/novell-filr1 /filr1_admin/data/btk7698.html). 


Configuring a Protected Identity Server Through 
Access Gateways 


These configuration steps assume that you are using SSL. For information about why to configure a 
protected Identity Server, see Protecting an Identity Server Through the Access Gateway in the NetIQ 
Access Manager 4.3 Installation and Upgrade Guide. 


1 (Conditional) If you are using domain-based multi-homing, create a wildcard certificate to be 
used by Identity Server and Access Gateway. 


For example, *.provo.novell.com, where Identity Server DNS is idp.provo.novell.com and 
Access Gateway DNS is jwilson1.provo.novell.com. 


If you don’t have a wildcard certificate, you cannot use domain-based multi-homing for this 
configuration scenario. 
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If you are using path-based multi-homing, you can use the same certificate for Identity Server 
and Access Gateway. 


2 Configure the Base URL of Identity Server. For complete configuration information, see 
Section 3.3, “Configuring an Identity Server,” on page 59. 


2a Click Devices > Identity Servers > Edit. 
2b Set the port to 443. 


When you change the base URL of the Identity Provider, all Access Manager devices that 
have an Embedded Service Provider need to be updated to import the new metadata. To re- 
import the metadata, configure the device so it does not have a trusted relationship with 
Identity Server, update the device, reconfigure the device for a trusted relationship, and 
update the device. For more information, see “Embedded Service Provider Metadata” on 
page 1197. 


2c Specify the correct domain name for the proxy service type. 


Path-Based Proxy Service: If you are using path-based multi-homing, the domain name of 
the Base URL must match the public DNS of the authentication proxy service set up in 
Access Gateway. 


For example, if your proxy service has a public DNS name of 
jwilson1.provo.novell.com, that is the domain name you must specify for the Base 
URL. 


Domain-Based Proxy Service: If you are using domain-based multi-homing, the domain 
name of the Base URL can be different than Access Gateway, but your DNS server must 
resolve the name to the IP address of Access Gateway. Specify a name that allows the two 
to share a common subdomain. 


For example, if the proxy service name is jwilson1.provo.novell.com, replace jwilson1 
with idp so that the domain name is idp.provo.novell.com. 


3 Configure Identity Server to use the correct certificate: 
3a Click the SSL Certificate icon. 
3b Click Replace, then click the Select Certificate icon. 


3c For a domain-based proxy service, select the wildcard certificate. For a path-based proxy 
service, select the certificate that matches the DNS name of Access Gateway. 


3d Click OK twice, then accept the prompt to restart Tomcat. 
4 Continue with Step 5 for a domain-based proxy service or Step 6 for a path-based proxy service. 
5 (Domain-Based Proxy Service) Set up a proxy service on Access Gateway for Identity Server: 
5a Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 


For more information about creating a proxy service, see Section 3.8.2, “Managing Reverse 
Proxies and Authentication,” on page 119. 


5b In the Proxy Service list, click New. 
5c Set the Multi-Homing Type field to Domain-Based. 
5d Set the following fields to the specified values: 


Published DNS Name: Specify the same name you have specified for the domain name of 
the Base URL of Identity Server. Your DNS server must be set up to resolve this name to 
Access Gateway. 


Web Server IP Address: Specify the IP address of Identity Server. If the cluster 
configuration for Identity Server contains more than one Identity Server, provide the IP 
address of one of the servers here. This must be the actual IP address of Identity Server 
and not the VIP address if Identity Server is behind an L4 switch. 
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Host Header: Specify Web Server Host Name. 


Web Server Host Name: Specify the domain name of the Base URL of Identity Server. 
This entry matches what you specify in the Published DNS Name field. 


Your proxy service configuration must look similar to the following: 


New Proxy Service x 


Proxy Service Name: Identity Server | 
Multi-Homing Type: Domain-Based v 

Published DNS Name: idp.provo.novell.com 

Path: 


Web Server IP Address: |10,10.15.206 


Host Header: web Server Host Name v 


Web Server Host Name: idp.prova.novell.com 


(Alternate Host Name) 


OK | Cancel | 


6 (Path-Based Proxy Service) Set up a proxy service on Access Gateway for Identity Server: 


6a Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 


For more information about creating a proxy service, see Section 3.8.2, “Managing Reverse 
Proxies and Authentication,” on page 119. 


6b In the Proxy Service list, click New. 
6c Set the Multi-Homing Type field to Path-Based and set the Path field to /nidp. 
6d Set the following fields to the specified values: 


Published DNS Name: Specify the same name you have specified for the domain name of 
the Base URL of Identity Server. Your DNS server must be set up to resolve this name to 
Access Gateway. 

Web Server IP Address: Specify the IP address of Identity Server. If the cluster 
configuration for Identity Server contains more than one Identity Server, provide the IP 
address of one of the servers here. This must be the actual IP address of Identity Server 
and not the VIP address if Identity Server is behind an L4 switch. 


Host Header: Specify Web Server Host Name. 


Web Server Host Name: Specify the domain name of the Base URL of Identity Server. 
This entry matches what you specify in the Published DNS Name field. 
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Your proxy service configuration must look similar to the following: 


New Proxy Service EJ 


Proxy Service Name: 
Multi-Homing Type: 
Published DNS Name: 
Path: 

Web Server IP Address: 


Host Header: 


Web Server Host Name: 
{Alternate Host Name) 


6e Click OK. 


Identity Server 


Path-Based v 


fnidp 


10,10, 15,206 


Web Server Host Name v 


jwilsont.provo,novell.com 


OK | Cancel | 


7 Configure a protected resource for the proxy service: 


7a In the Proxy Service List, click the link under the Protected Resources column. 


For more information about configuring protected resources, see “Configuring Protected 


Resources” on page 218. 


7b Click New, specify a name, then click OK. 


7c Configure the following fields: 


Authentication Procedure: Set this field to None. 


Identity Server needs to be set up as a public resource. 


URL Path: Set the path of the protected resource to the following value: 


/nidp/* 


Setting Up a Basic Access Manager Configuration 


223 


Your protected resource must look similar to the following: 


| | Overview \ Authorization \ Identity Injection \ Form Fill \ 

Protected Resource: idp 

Description: | 

Authentication Procedure: | [None] v| A 

URL Path List 
| New... | Delete 1 item(s} 
O URL Path 

O sénidps* 

7d Click OK. 


8 (Path-Based Proxy Service) Verify the configuration: 
8a Click the name of your path-based proxy service. 
8b Verify that the Remove Path on Fill option is not selected. 
8c Verify that the Path List has an entry with /nidp as the path for the protected resource. 
Your configuration must look similar to the following: 


EAFAM ua- Web Servers \ HTML Rewriting \ Logging \ 


Published DNS Name: jwilson1.provo.novell.com/ ... (1) path(s) 


Description: | | 


Cookie Domain: -provo.novell.com 


HTTP Options 


O Remove Path on Fill 


_| Reinsert Path in "set-cookie" Header 


New... | Delete | Enable SSL VPN... 1 item(s) 
C Path Protected Resource 
C snidp idp 

8d Click OK. 
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10 


12 


13 


Specify a host entry for Identity Server: 
9a Click Devices > Access Gateways > Edit > Hosts. 
9b Click New, specify the IP address of Identity Server, then click OK. 
9c In the Host Name(s) text box, specify the DNS name of Identity Server machine. 
You can also add the published DNS name of the base URL. 
9d Click OK. 


Set up Access Gateway to use SSL between the browsers and Access Gateway. See 
Section 17.5, “Configuring SSL Communication with Browsers and Access Gateway,” on 
page 993. 


Set up SSL between the proxy service that is protecting Identity Server and Identity Server. 


In this type of configuration, Identity Server is acting as a protected web server of Access 
Gateway. 


11a Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy 
Service] > Web Servers. 


For additional configuration information, see Section 17.6, “Configuring SSL between the 
Proxy Service and the Web Servers,” on page 995. 


11b Configure the following: 
Connect Using SSL: Enable this option. 
Web Server Trusted Root: Select Any in Reverse Proxy Trust Store. 
SSL Mutual Certificate: Do not configure this option. 
Connect Port: Specify 443. 


(Conditional) If the cluster configuration for Identity Server contains more than one Identity 
Server, configure the following options: 


12a Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy 
Service] > Web Servers. 


12b Specify the IP addresses of the other Identity Servers in the Web Server List. 


If Identity Servers are behind an L4 switch, you need to add the IP address of each Identity 
Server and not the VIP address. 


12c Click TCP Connect Options, then configure the following options. 
Policy for Multiple Destination IP Addresses: For Identity Servers, select Round Robin. 


Enable Persistent Connections: Make sure this option is selected. After the user has 
established an authenticated session with an Identity Server, you want that user to continue 
using the same Identity Server as long as that server is running. 


Configure HTML rewriting: 


13a Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy 
Service] > HTML Rewriting 


13b Make sure the Enable HTML Rewriting option is selected. 


13c In the HTML Rewriter Profile List, click New, then specify a name for the profile and select 
Word for the Search Boundary. 


13d Specify the following URLs in the And Requested URL Is Not section. The following URLs 
use jwilsoni.provo.novell.com/nidp as the DNS name of the proxy service for Identity 
Server. This is the example name for the path-based proxy service. 
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jwilsoni.provo.novell.com/nidp/idff/soap 
jwilson1.provo.novell.com/nidp/idff/soap/ 
jwilson1.provo.novell.com/nidp/idff/soap/* 
jwilsoni.provo.novell.com:443/nidp/idff/soap 
jwilson1.provo.novell.com:443/nidp/idff/soap/ 
jwilsoni.provo.novell.com:443/nidp/idff/soap/* 


Your rewriter profile must look similar to the following: 


Servers P Configuration P> Reverse Proxy P HTML Rewriting P 


HTML Rewriter: ag18 - DAL - sshost_1263408961113 - idp 
Specify URL and/or string rewriting for HTML documents. 


Requested URLs to Search 


If Requested URL Is 


New... | Delete 
Include URL 
All 


And Requested URL Is Not 


New... | Delete 
Exclude URL 


jwilsont.provo.novell.com/nidp/ idfff soap 
jwilsont. provo.novell.com/nidp/idfffsoap/ 
jwilson1. prove novell.com/nidp/idff/soap/* 
jwilson1. prove novell.com:443/nidp/idff/soap 
jwilson1.provo.novell.com:443/nidp/idff/soap/ 
jwilson1. provo novell.com:443/nidp/ idff/soap/* 


And Document Content-Type Header Is 
New... | Delete | Restore Defaults 
Content-Type Header 

text/html foefault} 


text/xml foefault? 
text/css foefault} 
text/javascript foefauit} 


application/javascript foefauit} 


D 0/0/20 0/0 


The example name for the domain-based proxy service is idp.provo.novell.com, which 
is the DNS name you would use when configuring the rewriter for a domain-based proxy 
service. 


13e Click OK. 
13f Use the up-arrow icon to move your profile to the top of the list. 
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14 Configure the Pin List so that Identity Server pages are not cached: 
14a On the Server Configuration page, click Pin List. 
14b In the list, click New, then specify the following values: 
URL Mask: Specify /nidp/* for the URL. 
Pin Type: Select Bypass. 


For more information about configuring a Pin list, see Section 4.3.3, “Configuring a Pin List,” 
on page 333. 


14c Click OK twice. 
15 Update Access Gateway. 


NOTE: If the SuSEFirewall is configured, after starting the firewall, all ports and services are blocked 
by default. You need to create filters to allow Access Gateway and any other service to communicate 
with Identity Servers. 


3.12 Sample Configuration for Protecting an 
Application Through Access Manager 


This section explains how to use Access Manager to protect the website illustrated in the following 
figure. The sample application that comes by default with the Access Manager Appliance showcases 
the various Access Manager features. Ensure that you remove the landing portal in the production 
environment. Instructions for removing this portal are given on the landing page. 


Figure 3-24 Digital Airlines Web Services 


rev 
digitalairlines Welcome: Tom log out > 


Our Customers œ Benefits «+ IT Services Employee Search GOP 


Company News 

Digital Airlines wins high profile © 3 

government contract. read Ky ; 
Corporate Mail Initiate VPN Session 

Online registration streamlined 

through Novell Access Manager. read 

Digital Airlines leverages Novell Medical Benefits Portal Sales System 


to enhance systems and products.read 


© digitalairlines. All Rights Reserved. | intranet help | feedback 


This section explains how to configure the Access Manager components to allow access to this first 
page and how to create and assign policies that protect the other pages. 
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3.12.1 


3.12.1.1 


The example web pages are designed to help network administrators understand the basic concepts 
of Access Manager by installing and configuring a relatively simple implementation of the software. 
The example serves as a primer for a more comprehensive production installation of Access 
Manager. 


¢ Section 3.12.1, “Installation Overview and Prerequisites,” on page 228 
¢ Section 3.12.2, “Setting Up the Web Server,” on page 230 
¢ Section 3.12.3, “Configuring Public Access to Digital Airlines,” on page 232 


¢ Section 3.12.4, “Implementing Access Restrictions,” on page 234 


Installation Overview and Prerequisites 


This section discusses the concepts involved in installing Access Manager to protect the example 
Digital Airlines website: 


¢ Section 3.12.1.1, “Installation Architecture,” on page 228 
¢ Section 3.12.1.2, “Deployment Overview,” on page 229 


After you deploy this example, you must understand the basic features of Access Manager and know 
how to configure the software to protect your own web servers and applications. 


Installation Architecture 


The diagram below illustrates how the Digital Airlines example is integrated with Access Manager. 


Figure 3-25 Digital Airlines Architecture 


Identity Server LDAP Server 


vn J 


Administration Console Access Gateway 


a! 


Web Servers 
This document explains how to use a browser machine and two other machines for this configuration. 


Table 3-3 Access Manager Components 


Administration Identity Access Application LDAP User Browser 
Console Server Gateway WebServer Store 

Machine 1 X X X X 

Machine 2 X 

Machine 3 X 
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3.12.1.2 


The simplified configuration described in this document is for a test environment only. It is not a 
recommended or supported configuration for a production environment. For example, the 
configuration database installed with Administration Console must not be used as an LDAP user 
store in a production environment. In a production environment, you would not want to install 
Administration Console, Identity Server, and web server on the same machine. This simplified 
configuration is designed to minimize the number of machines required for a tutorial. 


After deploying the Digital Airlines example, you must understand the concepts required to deploy 
Access Manager in a number of other configurations. In a production environment, you need to install 
the necessary Access Manager components according to your specific requirements. For more 
information about other possible installation configurations, see the /nstalling Access Manager in the 
NetlQ Access Manager 4.3 Installation and Upgrade Guide. 


Deployment Overview 


+ “Prerequisite Tasks” on page 229 
+ “Deployment Tasks” on page 229 


Prerequisite Tasks 
Before starting with the Digital Airlines example, you must perform the following tasks: 


O Enable pop-ups on a Firefox browser or Internet Explorer browser for managing and configuring 
the Access Manager components. For information about supported version of web browsers, 
see NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


O Install Access Manager Administration Console, Identity Server, and Access Gateway as 
described in the Installing Access Manager in the NetIQ Access Manager 4.3 Installation and 
Upgrade Guide. 


O Configure the Access Manager Identity Server. For configuration details, see Section 3.3, 
“Configuring an Identity Server,” on page 59. 


IMPORTANT: The Digital Airlines procedures explain how to add a user to the configuration 
store of Administration Console. These instructions assume that you have configured Identity 
Server to use this configuration store as the LDAP user store. This is not a recommended 
configuration for a production environment. To enable this configuration for a test environment, 
specify the IP address of Administration Console for the address of the server replica. 


Do not configure Access Gateway at this time. Other tasks explain how to configure Access Gateway 
to allow access to the Digital Airlines site on the web server. 


Deployment Tasks 
To configure access to the Digital Airlines site, you need to complete the following tasks: 
1. Set up the Apache web server on your Identity Server, then install the Digital Airline pages. 


For more information, see Section 3.12.2, “Setting Up the Web Server,” on page 230. 


2. Configure Access Gateway to protect the web server, but allow public access to the site. See 
Section 3.12.3, “Configuring Public Access to Digital Airlines,” on page 232. 


3. Configure Access Gateway to allow access to the protected pages. See Section 3.12.4, 
“Implementing Access Restrictions,” on page 234. 
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3.12.2 


3.12.2.1 


3.12.2.2 


230 


+ 


+ 


+ 


Setting Up the Web Server 


Section 3.12.2.1, “Installing the Apache Web Server and PHP Components,” on page 230 
Section 3.12.2.2, “Installing Digital Airlines Components,” on page 230 
Section 3.12.2.3, “Configuring Name Resolution,” on page 231 


Installing the Apache Web Server and PHP Components 


The following instructions are for SLES 11 SP1 and SP2. 


1 Download and install the Apache 2 and PHP 5 modules: 


1a On your SLES 11 SP1 and SP2 server, click the YaST icon, provide your root password if 
requested, then click OK. 


1b In the YaST left navigation window, click the Software icon, then click Software 
Management. 


The YaST software Search screen must open. 
1c In the Search field, type Apache2, then click Search. 
All available Apache 2 software packages are listed. 
1d If they are not already selected, select the following Apache 2 check boxes: 
apachez2: Specifies the Apache 2.0 web server. 
apache2-mod_php5: Specifies the PHP5 module for Apache 2.0. 
apache2-prefork: Specifies the Apache 2 prefork multiprocessing module. 
apache2-worker: Specifies the Apache 2 worker multiprocessing module. 
le Click Accept. 


1f Verify that the php5 package is also selected for install, then click Continue to install that 
package as well as the other dependent packages. 


2 Configure SUSE to start the Apache server during boot up: 


2a In the YaST left navigation window, click Network Services > HTTP Server. 


2b In the HTTP Server Wizard, enable the Start Apache2 Server When Booting option, then 
click Finish. 


2c Reboot the server or manually start the Apache server. 


Installing Digital Airlines Components 


The Digital Airlines example package contains the following components: 


+ 


+ 


+ 


+ 


vpn.html: Specifies the GUI interface page for initiating a VPN session. 

sales.php: Contains the sales PHP database files associated with the example. 
payroll.html: Specifies the GUI interface page for initiating a payroll session. 
medical.html: Specifies the GUI interface page for initiating a VPN session. 

index.php: Contains the welcome HTML index file for establishing secure authentication. 
sales: Specifies a subdirectory that can be configured to require basic authentication. 
images: Contains all image files associated with the example. 
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In this example configuration, you use Access Gateway to protect the Digital Airlines website, which 
is installed on your Identity Server. This section describes where your example Digital Airlines 
components are located and how to add them to your Identity Server. 


1 Download the Digital Airlines Sample Pages (https:/Awww.netiq.com/documentation/access- 
manager-41/resources/htdocs.tar.gz). 

2 Extract htdocs.tar.gz to a root directory of the web server. For an Apache 2 web server on 
SLES 11 SP1 and SP2, extract the files to the following directory: 
/srv/www/htdocs/ 

3 Determine the DNS name and IP address of the SUSE Linux server on which your example files 
are installed: 
3a Log in to the YaST as the root user. 


3b Click Network Services > Host Names, then write down the IP address and hostname of 
your server: 


IP Address: 


Hostname: 


As required later in the installation (see Step 7 on page 106), you must provide the host 
name and server configuration information to establish the network connection between the 
web server you are protecting (the server where your web service components are located) 
and Access Gateway. 


4 Continue with “Configuring Name Resolution” on page 231. 


Configuring Name Resolution 


Identity Server needs to resolve the DNS name of Access Gateway, Access Gateway needs to 
resolve the DNS name of Identity Server, and the client that is accessing the Digital Airlines site 
needs to be able to resolve the names of both Access Gateway and Identity Server. 


You can either set up your DNS server to resolve the DNS name of Identity Server and Access 
Gateway to the correct IP address, or you need to modify the hosts file on the various machines to 
perform the resolution. 


Each platform has its own location for the host file. 


Platform Location 
Windows \WINDOWS\SYSTEM32\DRIVERS\ETC\HOSTS 
Linux /etc/hosts 


Client: The hosts file of the client machine needs to contain entries for Identity Server and Access 
Gateway. 


Identity Server: The hosts file on Identity Server needs to contain an entry for Access Gateway. 
Access Gateway: The hosts file on Access Gateway needs to contain an entry for Identity Server. 


e Access Gateway Appliance: Do not manually edit the hosts file on Access Gateway 
Appliance. The file is overwritten every time the configuration is updated with the entries 
specifies on the Hosts page. To add an entry to the Hosts page, click Devices > Access 
Gateways > Edit > Hosts, then click New. The entries on this page are written to the hosts file 
when the configuration is updated. 
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3.12.3 


+ 


Access Gateway Service: You can edit the hosts file on Access Gateway Service. Add an 
entry that allows Access Gateway Service to resolve the name of Identity Server. 


Continue with Section 3.12.3, “Configuring Public Access to Digital Airlines,” on page 232. 


Configuring Public Access to Digital Airlines 


This section describes the procedures for configuring Access Gateway so that a client can access the 
Digital Airlines site. Before continuing, make sure you have completed the prerequisite tasks 
described in “Prerequisite Tasks” on page 229 and Section 3.12.2, “Setting Up the Web Server,” on 
page 230. 


1 
2 


On the client machine, open a browser and log in to Administration Console. 
Click Devices > Access Gateways. 


The IP address or name of Access Gateway you installed must be listed in the display window. 


Access Gateways 


Access Gateway Servers 


New Cluster... | Restart | Stop | Refresh | Actions w 
C] Name Status Health Alerts Commands Statistics Type Configuration 
Fj azgi8 Current D 0 Succeeded View Gateway Appliance Edit 


An Access Gateway that has not been configured displays a yellow health status. 
Click Edit > Reverse Proxy / Authentication. 


4 In the Identity Server Cluster option, select the configuration you have assigned to Identity 


Server. 


This sets up the trust relationship between Access Gateway and Identity Server that is used for 
authentication. 


In the Reverse Proxy List, click New, specify DAL as the new Reverse Proxy Name, then click 
OK. 


Enable a listening address. 


If the server has only one IP address, only one is displayed and it is automatically selected as 
the Listening Address. If the server has multiple addresses, you can select one or more IP 
addresses to enable. You must enable at least one address by selecting its check box. 


Configure a listening port. 
Non-Secure Port: Select 80, which is the default port for HTTP. 


Secure Port: This is the HTTPS listening port. This port is unused and cannot be configured 
until you enable SSL. This configuration scenario does not contain SSL configuration 
instructions. 


In the Proxy Service List, click New and specify the following information: 


Proxy Service Name: Specify any name that intuitively identifies this service on your Access 
Gateway server. For this example, specify Dallistener. 


Public DNS Name: The DNS name you want the public to use to access your Digital Airlines 
site. This DNS name must resolve to the IP address you set up as the listening address. This 
example uses am3bc.provo.novell.com. 


Web Server IP Address: The IP address of the web server where your Digital Airlines files are 
installed. 
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14 
15 


16 
17 


18 


19 


Host Header: Select Forward Received Host Name from the drop-down menu. The web server 
and the Digital Airlines pages have not been set up to require the DNS name of the web server in 
the Host Header, so it does not matter what name is placed in the Host Header. 


Your form must look similar to the following: 


New 
Proxy Service Name: Dallistener 
Published DNS Name: am3bc. provo. novell. com 


Web Server IP Address: (10.10.16.46 


Host Header: 


web Server Host Name: | 


(Alternate Host Name} 


Click OK. 
In the Proxy Service List, click Dallistener. 
Click Protected Resources, then in the Protected Resource List, click New. 


Type everything in Name, then click OK. 
In the Authentication Procedure field, select None from the drop-down menu. 
Under URL Path List, you must see /*, which includes everything on that server. 


Later on, you will be instructed to change the Authentication Procedure field to a Name/ 
Password - Form, but for now, we want you to learn how the example works without any 
authentication. 


Click OK. 


In Protected Resource List, verify that the protected resource you created is enabled, then click 
OK. 


Click the Devices > Access Gateways. 
To apply the changes, click Update > OK. 


Until this step, nothing has been saved. The Update status pushes the configuration to the 
server. When the configuration update has completed successfully, the server returns the status 
of Current. 


To update Identity Server for the trusted relationship, click Devices > Identity Servers, then click 
Update > OK. 


To test the results, complete the following. 
19a Open a browser on the client machine. 
19b Enter the URL for the proxy service. For this example, it is 


am3bc.provo.novell.com 


Your network needs to be configured so that this published DNS name of the proxy service 
resolves to the IP address of Access Gateway. The reverse proxy hides the internal address 
of the web server. 
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You must see the Digital Airlines page. 


Digital Airlines Intranet - Mozilla Firefox = {Dj xj 
File Edit view Go Bookmarks Tools Help i? 


KE Ke >> 7 & (2) A | http://am3bc.provo.novell.com -| © co | 


a 


OA 
ge ~S 
digitalairlines!ntranet log out > 


Our Customers + Benefits + IT Services Employee Search | | GOP 


Company News 

Digital Airlines wins high profile (5) © 

government contract. read z 
Corporate Mail Initiate VPN Session 

Online registration streamlined 

through Novell Access Manager. read 

Digital Airlines named "Company 

ofthe Year" by Airline Weekly. read 

Digital Airlines leverages Novell Medical Benefits Portal 

to enhance systems and products read 

© digitalairlines. All Rights Reserved. | intranet help | feedback >| 


If you get an error, check the time on Access Gateway and Identity Server. Their time must 
be synchronized and must be within 5 minutes of each other. 


20 Close the browser. 


21 To require authentication for access to the site and to configure access to the protected pages 
(the VPN application and the hidden Sales System site), continue with Section 3.12.4, 
“Implementing Access Restrictions,” on page 234. 


Currently, the Corporate Mail and Medical Benefits Portal buttons do not link to available pages. 
They exist to illustrate what you could do when you require your users to authenticate before 
accessing the site. 


For example, the Corporate Mail button could be configured so that the redirected request 
initiates a mail session to the user’s default e-mail application and injects the login credentials to 
provide access to the user’s protected, Web-based e-mail account. 


The Medical Benefits Portal button could be configured to set up a federated account with the 
company that provides medical benefits for your company. 


3.12.4 Implementing Access Restrictions 


234 


After you access the Digital Airlines site as a public resource (see Section 3.12.3, “Configuring Public 
Access to Digital Airlines,” on page 232), you can configure the site for authentication and 
authorization requirements. This section describes the following tasks: 


¢ Section 3.12.4.1, “Enabling an Authentication Procedure,” on page 235 
¢ Section 3.12.4.2, “Configuring a Role-Based Policy,” on page 236 
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¢ Section 3.12.4.3, “Assigning an Authorization Policy to Protect a Resource,” on page 243 
¢ Section 3.12.4.4, “Configuring an Identity Injection Policy for Basic Authentication,” on page 246 


3.12.4.1 Enabling an Authentication Procedure 


After hiding the internal web server behind Access Gateway, you can add an authentication method 
to the website by using the following procedure: 

1 Click Devices > Access Gateways > Edit. 

2 Click DAL > Dallistener > Protected Resources > everything. 


3 In the Authentication Procedure field, select Name/Password - Form. 


IMPORTANT: Make sure to select the Name/Password - Form from the drop-down menu. 
Secure Name/Password does not work correctly if the base URL for Identity Server is HTTP. 


4 Click OK to return to the Protected Resources page. 
5 Click Devices > Access Gateways, then click Update > OK. 


This pushes the new configuration to the server. When the configuration process is complete, 
the status returns to Current. 


6 To test the results, open a browser and enter the URL of your website. 
The website must now be protected and require you to log in by using a name and password. 
7 Enter the credentials of the admin user of your Administration Console. 


The Digital Airlines site appears. If you receive an error, see “Common Authentication Problems” 
on page 235. 


8 Close all sessions of the browser. 


The Digital Airlines page has a logout graphic, but it isn’t an action. The current session is active 
until you log out (which isn’t possible), until the session times out (the default value is 20 
minutes), or you close all sessions of the browser. 


9 Continue with “Configuring a Role-Based Policy” on page 236. 


Common Authentication Problems 
In this basic configuration there are two common configuration errors that can cause login to fail: 


Error 300101015: If your Access Gateway and Identity Server do not have the same time, the 
assertion is invalid. Check the time of each machine. 


Errors 100101043 and 100101044: Identity Server and Access Gateway need to be able to resolve 
each other’s DNS names. If you are in a lab and not using a DNS server, make sure the host files of 
each machine have been configured to resolve the DNS name to the IP address of the device. 


The other cause for these errors, when SSL has not been enabled, is the failure to update either 
Identity Server or Access Gateway after making a change to the base URL of Identity Server or 
modifying Identity Server Access Gateway is trusting for authentication. 


For information about how to force Access Gateway to update the metadata for Identity Server, see 
“Embedded Service Provider Metadata” on page 1197. 
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3.12.4.2 


Configuring a Role-Based Policy 


You learned how to set up and configure Access Manager to protect a basic web service. Access 
Manager also uses role-based access control (RBAC) to conveniently assign a user to a particular 
job function or set of permissions within an enterprise, in order to control access. 


Access Manager enables you to assign roles to users, based on attributes of their identity, and then 
associate policies with the roles. In designing your own actual production environment, you need to 
decide which roles you need (such as, sales, administrative, and accounting). You create Role 
policies that assign the roles to your users, and then you create Authorization and Identity Injection 
policies that use the roles to control access. 


This section explains how to set up an Identity Injection policy that customizes the main page of the 
Digital Airlines site. When the index.php page has access to the user’s name, the main page displays 
the name. If the user belongs to the sales_role role, the Sales System button is displayed on the 
page. 


To configure an Identity Injection policy that uses a role, complete the following tasks: 
e “Adding an LDAP Attribute to Your Configuration” on page 237 
e “Creating a Sales Role” on page 237 
¢ “Creating a New User with a Sales Role” on page 239 


e “Creating the Identity Injection Policy for a Custom Header” on page 240 


236 Setting Up a Basic Access Manager Configuration 


Adding an LDAP Attribute to Your Configuration 


The LDAP attribute that is added in this section is an LDAP attribute assigned to the User class in 


eDirectory. This attribute is used to assign users to the sales role. 


1 Click Devices > Identity Servers, then click Shared Settings > Custom Attributes. 


Identity Servers 


Servers Mer Tae 1 


Attribute Sets | User Matching Expressions | |Custom Attributes | | Authentication Card Images 


Add custom shared secret names or LDAP attribute names that you want to be selectable in policy select lists. 


Shared Secret Names | 


New | Delete 
C] Name Entries 


No items 


LDAP Attribute Names 


New | Delete | SetEncode | Clear Encode 
C] Name 64-bit Encode Attribute Data 


C] audio 

C] businessCategory 
carlicense 

cn 
departmentNumber 


displayName 


D 00 0 a 


employeeNumber 


[C] employeeType 


2 In the LDAP Attribute Names section, click New, type description in the Name field, then click 


OK. 


This adds the description attribute to the policy list of available LDAP attributes, and you can use 


this attribute to assign a role to your users. 
3 Click Close. 
4 Continue with “Creating a Sales Role” on page 237. 


Creating a Sales Role 


Use the following procedure to create a sales role for the Digital Airlines example. (For more 
information about Role policies, see Chapter 8.2, “Role Policies,” on page 721.) 
1 Click Devices > Identity Servers, then click Edit > Roles. 
2 In the Roles Policy List section, click Manage Policies. 
3 In the Policy List section, click New, then fill in the following fields: 
Name: Specify Sales Role. 
Type: Select Identity Server: Roles. 
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4 Click OK to open the policy editor. 


Edit Policy: Sales_Role - Rule 1 
Type: Identity Server: Roles 


Description: | 
Priority: | 1 ~] 
Conditions Condition structure: | AND Conditions, OR group: ~] 


Condition Group 1 
New w 


No conditions in Rule 1. (Actions will always occur unconditionally. ) 


Actions 


Activate Role 
No Actions in Rule T 


Changes made on this panel must be applied from the Policies Panel. 


oK =| Cancet | 


In Condition Group 1, click New > LDAP Attribute, and assign the following values: 


LDAP Attribute: Select description. (If description is not included in the LDAP Attribute list, 
you can add it from this page. For instructions, see Step 5a through Step 5c.) 


Comparison: Select String: Contains Substring. 

Mode: Select Case Insensitive. 

Value: Select Data Entry Field (from the drop-down box); specify Sales as the value. 
Result on Condition Error: Select False. 


If the description attribute is not listed in the LDAP Attribute drop-down menu, create it by 
following this procedure: 


5a In Condition Group 1, click New > LDAP Attribute, scroll to the bottom of the list, then click 
New LDAP Attribute. 


5b In the Name field, specify description, then click OK. 
5c In the LDAP Attribute field, select description from the drop-down menu. 


In the Actions section, click New > Activate Role, then specify sales_role in the Do Activate Role 
field. Your rule must look similar to the following: 
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Edit Rule: Sales_Role - Rule 1 


Type: Identity Server: Roles 
Description: 
Priority: 1 
Conditions Condition structure: AND Conditions, OR groups Y 


Condition Group 1 


New v 


lif ~| LDAP Attribute: description ¥ 


Comparison: String : Contains Substring Y 


Mode: Case Insensitive w 


Value: Data Entry Field ©: Sales 


Result on Condition Error; False w 


Append New Group | 


Actions 


New v 


Do Activate Role 


sales_role| 


The value for Activate Role might be case sensitive. If you are going to inject this role into a 
policy for a web server, and the page on the web server is configured so that it evaluates case, 
make sure the value entered here matches what is expected on the web server. The Sales 
System button on the Digital Airlines site requires that this value be lowercase: sales_role. 


7 Click OK to close the Rule editor, then click OK to close the Rule List. 
8 To save the Role policy, click Apply Changes, then click Close to return to the Roles Policy List. 


9 In the Roles Policy List, select Sales_Role, then click Enable. 


10 
11 


12 


Roles Policy List 


Manage Policies | Enable | Disable 


M Name Enabled Policy Container Description 


[ Sales Role W Master_Container 


Click OK. 

Update Identity Server. 

Wait for the Status to return to Current. 

Continue with “Creating a New User with a Sales Role” on page 239. 


Creating a New User with a Sales Role 


After you have created a user policy, only users provisioned with that policy can access the protected 
web resource. This section describes how to create a user that meets the conditions to be assigned 
the Sales role. These instructions assume that you are using the configuration store of Administration 
Console as the LDAP user store. If you are using a different server than the LDAP user store, you 
need to modify these instructions: 


1 
2 


Click <user name> at the top right of the page and then click Manage Roles & Tasks. 
Click Users. 
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3 Click Create User, then fill in the following fields: 
Username: Specify Tom. 
First name: Specify Tom. 
Last name: Specify Tester. 


Context: Click the Object Selector icon, then click novell. The user is automatically assigned 
the context of novell. 


Password: Assign a password to the user. 
Retype password: Retype the assigned password. 
Your user entry must look similar to the following: 


& Create User [?] 
*srequired 

Username: * [Tom 

First name: Tom 


Last name: * [Tester 
Full name: [Tom Tester 
Context: * [novell a 


Password: pa 
Retype password: [roses 


Note: Failure to enter a password will allow the user to login without a password. 


4 Scroll to the Description field, then click the + icon. 


5 In the Add text box, type Sales (initial uppercase), then click OK to return to the Create User 
page. 

6 On the Create User page, click OK, then click OK to close the Create User task. 
Tom meets the requirements to be assigned the Sales role when he logs in. 


7 Continue with “Creating the Identity Injection Policy for a Custom Header” on page 240. 


Creating the Identity Injection Policy for a Custom Header 


The following policy injects the user’s roles and DN into a custom header. The index.php page reads 
this information and uses it to display the user’s name. If the user is assigned the sales_role, the 
Sales System button is displayed on the main page. 


1 Click Devices > Access Gateways, then click Edit > DAL > Dallistener > Protected Resources > 
everything. 

2 Click Identity Injection > Manage Policies. 

3 In the Policy List section, click New, then fill in the following: 
Name: Specify Custom_Injection. 


Type: Select Access Gateway: Identity Injection. 
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4 In the Actions section, click New > Inject into Custom Header. 


5 To inject the user’s name, fill in the following values: 
Custom Header Name: Specify X-Name. 


Value: Select Credential Profile. The LDAP Credentials: LDAP User Name is selected 


automatically for you. 


for the second custom header: 
Custom Header Name: Specify X-Role. 
Value: Select Roles. 


Your policy must look similar to the following: 


Edit Rule: Custom_Injection - Rule 1 


Type: Access Gateway: Identity Injection 
Description: 

Priority: 1 & 

Actions 


New v 

Do Inject into Custom Header 
Custom Header Name: 
¥-Name 


Value: Credential Profile ©  : LDAP Credentials:LDAP User Name Y 


Multi-Value Separator; , vY 

DN Format: LDAP (ex, cn=jsmith,ou=Sales,o=Novell) w 
And Inject into Custom Header 

Custom Header Name: 

¥-Role 

Value: Roles w 


Multi-Value Separator: ,¥ 


DN Format: LDAP (ex, cn=jsmith,ou=Sales,o=Novell] v 


Changes made on this panel must be applied from the Policies Panel. 


oK | Cancet | 


7 Click OK twice, then click Apply Changes. 
8 Click Close. 


10 


12 


In the Identity Injection Policy List section, select Custom_Injection, then click Enable. 


Click OK. 
Click Devices > Access Gateways, then click Update > OK. 


To test Tom’s access rights, complete the following steps: 


12a Open a new browser, then enter the URL of the Digital Airlines website you created. 


In this example, it is am3bc.provo.novell.com. 


12b When prompted for user ID and password from Access Manager, log in with Tom’s 


credentials. 
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To inject the user’s roles, click New > Inject into Custom Header, then fill in the following values 
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The page appears with a Welcome: Tom message at the top, and the Sales System button 
appears in the lower right corner of the page. 


Oy 


digitalairlines! Welcome: Tom log out > 


Our Customers «+ Benefits «+ IT Services Employee Search GOP 


Company News 

Digital Airlines wins high profile © © 

government contract. read oe $ 
Corporate Mail Initiate VPN Session 

Online registration streamlined 

through Novell Access Manager. read 

Digital Airlines named "Company 

ofthe Year" by Airline Weekly. read 

Digital Airlines leverages Novell Medical Benefits Portal Sales System 

to enhance systems and products.read 


digitalairlines. All Rights Reserved. | intranet help | feedback 


12c Click the Sales System button, and the Sales page appears. 
If the Sales System button does not appear, Tom was not assigned the sales_role: 


¢ Verify that the role policy is enabled for Identity Server by clicking Policies > Policies, 
and confirm that Identity Server is listed in the Used By column for the policy. 


+ On the Policies page, confirm that Access Gateway is listed in the Used By column for 
the Identity Injection policy. 


+ Discover whether there was an error in the Role policy evaluation. Click Auditing > 
General Logging, then download the catalina. out (Linux) or the stdout .log 
(Windows) file for Identity Server. Search for the name of the role policy and determine 
whether the role was successfully assigned. 


+ Determine whether there was an error in Identity Injection policy evaluation. Click 
Auditing > General Logging, then download the catalina. out (Linux) or the 
stdout .log (Windows) file for Access Gateway. Search for the name of the Identity 
Injection policy and determine whether its values were successfully injected. 


For more information about troubleshooting policies, see Section 30.6, “Troubleshooting 
Access Manager Policies,” on page 1226. 


12d Close all sessions of the browser. 


13 To test that the sales _role is required for the Sales System button to appear, complete the 
following steps: 


13a Open a new browser, then enter the URL of the Digital Airlines website you created. 
In this example, it is am3bc.provo.novell.com. 


13b Log in as the admin user. The page must have a Welcome: admin at the top of the page, 
but the Sales System button must not appear. 


13c To the URL, add /sales, and the Sales page appears. 
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This illustrates that although the link is hidden, the Sales page is not protected. 
13d Close all sessions of the browser. 
14 Continue with “Assigning an Authorization Policy to Protect a Resource” on page 243. 


3.12.4.3 Assigning an Authorization Policy to Protect a Resource 


Use the following procedure to limit access to the Sales page based on the sales role: 


For the Authentication Procedure, select Name/Password - Form. 
In the URL Path List, click /*, modify it to specify /sales/*, then click OK. 
Your protected resource must look similar to the following: 


| Overview ' Authorization \ Identity Injection \ Form Fill \ 


Protected Resource: sales_page 


A WN PF 


Description: 


Authentication Procedure: | Name/Password - Form (20) v |Z 

URL Path List 

New... | Delete 1 item(s) 
C URL Path 

C] fsales/* 


5 Click Authorization > Manage Policies. 

6 Click New, then fill in the following fields: 
Name: Specify Allow Sales. 

Type: Select Access Gateway: Authorization. 

7 Click OK. 

The Edit Policy page appears. 

8 In Condition Group 1, click New > Roles, then specify the following values: 
Comparison: Select String: Contains Substring. 
Mode: Select Case Insensitive. 

Value: Select Roles: sales_role. 
Return on Condition Error: Select False. 
9 In the Actions section, ensure that Permit is selected. 
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In the Protected Resource List, click New, specify sales_page for the name, then click OK. 


Click Devices > Access Gateways, then click Edit > DAL > Dallistener > Protected Resources. 
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Your rule must look similar to the following: 


Edit Rule: Allow_Sales - Rule 1 


Type: Access Gateway: Authorization 


Description: Permit rule for the sales_role. 


Priority: 1 ¥ 


Conditions Condition structure: | AND Conditions, OR groups Vv 


| Condition Group 1 


Roles: [Current] Y (i) 


Comparison: String : Contains Substring Y 
Mode: Case Insensitive w 
Value: Roles w sales_role w 


Result on Condition Error: Fase w 


Append New Group | 


Actions 


Changes made on this panel must be applied from the Policies Panel. 


ok | Cancel | 


This rule allows everyone assigned to the sales_role to have access. 
10 Click OK. 
11 In the Rule List, select New. 
This second rule is a general deny rule for everyone who has not been assigned the sales_role. 
12 Make sure the Priority field is set to 10 and that the Condition Group 1 has no conditions. 
13 In the Actions section, click Permit, select Deny, then select Deny Message. 


14 Click Message Text, then in the text box, type the deny message: Sorry, you must work in sales 
today. 
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Your rule must look similar to the following. 


Edit Rule: Allow_Sales - Rule 2 


Type: Access Gateway: Authorization 


Description: General deny rule | 


Priority: 10 ~ 


Conditions Condition structure: | AND Conditions, OR groups 


v 


Condition Group 1 


New v 
No conditions in Rule 2. (Actions will always occur unconditionally, ) 


Actions 


Do Deny v Deny Message V 
Message Text Y Sorry, you must work in sales today. 


Changes made on this panel must be applied from the Policies Panel. 


OK =| Cancel | 


With no conditions in the condition group, this creates a general deny rule that matches 
everyone. The users who have been assigned the sales role match the first rule that is 
processed. Everyone else matches this general deny rule. 


Click OK to close the rule editor, then click OK to close the Rule List. 

In the Policy List window, click Apply Changes, then click Close. 

In the Authorization Policy List, select the Allow_Sales policy, then click Enable. 

Click OK. 

Click the Access Gateways link, then click Update > OK. 

Test the results: 

20a Open a new browser, then enter the URL of the Digital Airlines website you created. 
In this example, it is am3bc.provo.novell.com. 

20b Log in as the admin user. 

20c Add /sales to the URL. 


You must receive the following response window with the message derived from Access 
Gateway you just configured: 


o 


Status: 403 Forbidden 
Description: Sorry, you must work in sales today. 


If this condition persists, please contact the helpdesk. 


Now, only users with an assigned sales role can access the Sales page. 
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3.12.4.4 


21 Test the results with a user who has the sales role: 
21a Open anew browser, then enter the URL of the Digital Airlines website you created. 
In this example, it is am3bc.provo.novell.com. 
21b Login as Tom. 
21c Click the Sales System button or add /sales to the URL. 
The Sales page is displayed. 
21d Close all sessions of the browser. 
22 Continue with “Configuring an Identity Injection Policy for Basic Authentication” on page 246. 


Configuring an Identity Injection Policy for Basic Authentication 


A common way to protect web resources is to configure the web server to require basic 
authentication for accessing a resource. The web is configured to check for the user’s name and 
password in the HTTP authentication header. If you have web resources with this type of 
configuration, you can enable single sign-on to these resources by creating a policy that injects the 
username and password into the HTTP authentication header. 


This section explains how to set up the /sales directory to require basic authentication, and then 
how to create the Identity Injection policy. 

¢ “Configuring the Web Server for Basic Authentication” on page 246 

¢ “Creating an Identity Injection Policy for Basic Authentication” on page 248 


Configuring the Web Server for Basic Authentication 


It is difficult to create a configuration on the Apache web server that provides consistent results by 
using LDAP SSL for basic authentication. Because this is a tutorial and is expected to be 
implemented in a testing environment, the following steps explain how to configure Apache to allow 
for a clear-text password over LDAP and how to configure basic authentication in this environment. 
The purpose of this section is not to explain how to configure Apache, but to explain how you can 
enable single sign-on for web resources that require basic authentication. 

+ “Enabling LDAP Clear-Text Passwords” on page 246 


¢ “Enabling Basic Authentication” on page 247 


Enabling LDAP Clear-Text Passwords 
To turn off the SSL requirement on the internal LDAP user store: 


1 Log in to Administration Console. 


2 Click the View Objects ®© icon in the top menu bar. 

3 Click Search, then configure the following fields. 
Context: Accept the default [root] value and leave the Search sub-containers option enabled. 
Name: Accept the default wildcard value. 
Type: Select LDAP Group from the list. 


4 Inthe Results section, click the LDAP Group - <your server name> object, then select Modify 
Object. 


5 Select the LDAP Allow Clear Text Password attribute, then click Edit. 
6 Select the check box, then click OK. 
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10 


Click OK or Apply at the bottom of the page. 
If you do not click one of these buttons, your modifications are not saved. 


To return Administration Console machine to its default view, click the Access Manager icon in 
the top menu bar. 


From a terminal window on Administration Console machine, log in as root. 


Restart eDirectory with the following command: 


/etc/init.d/ndsd restart 


Enabling Basic Authentication 


You need to enable the Apache server to require basic authentication for the /sales directory. On 
SLES 11 SP1 and SP2, you need to enable two authentication modules and modify an Apache 
configuration file. 


1 
2 
3 
4 
5 
6 


7 


8 


At the Apache server machine, log in to YaST. 

Click Network Services > HTTP Server > Server Modules. 
Scroll down, then enable the Idap and authnz_Idap modules. 
Click Finish. 

In a text editor, open the /etc/apache2/httpd.conf file. 
Add the following section to the end of the file: 


<Directory "/srv/www/htdocs/sales"> 
Options Indexes FollowSymLinks 
AllowOverride None 
order allow, deny 
allow from all 
AuthType Basic 
AuthName Internal 
AuthBasicAuthoritative off 
AuthBasicProvider ldap 
AuthzLDAPAuthoritative off 
AuthLDAPURL ldap://127.0.0.1/o0=novell?uid??(objectclass=* ) 
require valid-user 
AuthLDAPBindDN cn=admin, o=novell 
AuthLDAPBindPassword novell 
</Directory> 


Replace the information in the AUthLDAPURL line with the information the IP address of your 
LDAP user store. Modify the query string to match your user store. This sample line assumes 
that the web server and your LDAP user store are installed on Administration Console, and 
127.0.0.1 is its internal address. 


The AuthLDAPBindDN and AuthLDAPBindPassword contain the distinguished name of a user 
and that user’s password. This user needs sufficient rights to log in to the LDAP user store and to 
search for the users in the tree. 


Restart the Apache server with the following command: 
/etc/init.d/apache2 restart 


To test that the /sales directory now requires basic authentication: 
8a Open a new browser, then enter the URL of the Digital Airlines website you created. 


In this example, it is am3bc.provo.novell.com. 


Setting Up a Basic Access Manager Configuration 247 


248 


8b Log in using the credentials for Tom. 


Even though Tom has logged in and been assigned the correct role, he is prompted to log in 
again to access the /sales directory. To enable single-sign on, you must create an Identity 
Injection policy that injects Tom’s credentials into the authentication header. 


9 Continue with “Configuring the Web Server for Basic Authentication” on page 246. 


Creating an Identity Injection Policy for Basic Authentication 


This section explains how to enable single sign-on by creating an Identity Injection policy that injects 
the user’s authentication credentials into a header. The web server uses the credentials in the 
authentication header to satisfy its login requirements. 

Click Devices > Access Gateways, then click Edit > DAL > Dallistener > Protected Resources. 
In the Protected Resource List, click sales_page. 


Click Identity Injection > Manage Policies > New. 


A WN FP 


For the new policy, fill in the following fields: 

Name: Specify Basic _Auth for the name. 

Type: Select Access Gateway: Identity Injection for the type. 
5 Click OK. 


6 Inthe Actions section, click New, select Inject into Authentication Header, then select the 
following values: 


User Name: Select Credential Profile. The LDAP Credentials: LDAP User Name value is 
automatically selected for you. This credential is the cn attribute of the user. 


Password: Select Credential Profile. Click LDAP Credentials: LDAP User Name, then select 
LDAP Credentials > LDAP Password. 


Your policy must look similar to the following: 


Type: Access Gateway: Identity Injection 
Description: Authentication header policy 
Priority: 1 

Actions 


New w 


Do Inject into Authentication Header 
User Name: Credential Profile w : LDAP User Name w 
Password: Credential Profile w : LDAP Password w 


Multi-Value Separator; ,¥ 


DN Format; LDAP fex, cn=jsmith,ou=Sales,o=Novell] v 


Changes made on this panel must be applied from the Policies Panel. 


OK Cancel | 


7 Click OK to close the policy editing page, then click OK to close the Rule List page. 
8 In the Policy List page, click Apply Changes, then click Close. 
9 Select the Basic Auth check box, click Enable, then click OK. 
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10 Click OK to return to the Protected Resource List. Your list must look similar to the following: 


Protected Resources: ag18 - DAL - Dallistener 


Proxy Service \ Web Servers \ HTML Rewriting 


Protected Resources 


Logging \ 


Web Server Resources being made Public or being Protected by an Authentication Procedure and/or Authorization Policies, 


Select the Policy View to see which Protected Resources are using each Policy, Click the "Used By" link (an the Policy View) to assign a Policy to more than 


one Protected Resource at a time. 


Resource View VW 


| Enable 
Enabled URL Paths 


New... | Disable 


CO Name 


| Delete 


Authentication Procedure 


Protected Resource List 


2 item(s) 


Authorization Identity Injection Form Fill Description 


O everything v 1 Paths Y Name/Password - Form lone DAL Injection one 


Fj “sales. page KA 1 Paths ¥ 


Name/Password -Form 


Basic Auth f one 


-Allow Sales 


11 To save your configuration changes, click the Access Gateways link, then click Update > OK. 


12 To test the configuration: 


12a Open a new browser, then enter the URL of the Digital Airlines website you created. 


In this example, it is am3bc.provo.novell.com. 


12b Log in as Tom. 


The Digital Airlines site must appear with the Sales System button. 


A 
digitalairlinesintranet 


log out > 


Welcome: Tom 


tz x 


Employee Search © GOP 


Our Customers + Benefits + IT Services 
Company News 
Digital Airlines wins high profile © @ 
government contract. read 
Corporate Mail Initiate VPN Session 

Online registration streamlined 
through Novell Access Manager. read 
Digital Airlines named "Company 
of the Year" by Airline Weekly. read 

Medical Benefits Portal Sales System 


Digital Airlines leverages Novell 
to enhance systems and products. read 


digitalairlines. All Rights Reserved. | intranet help | feedback 


12c Click the Sales System button. You must have access to the Sales System site, as shown 


below: 
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digitalairlines!ntranet 


- 


a S 


= 


Sales System 


4 JasonJones 12 JAN 2006 
w Digital Airlines Simplifies Buying Programs 


Success Stories Competitive Info 
Get the latest and greatest success stories. Get the latest and greatest competitive 
information. 
@ Digital Airlines lands wins large 
government contract. @ Inside competitor information available. 

+ Search for a Reference/Success Story + competitive zone 

+ Submit a Reference/Success + competitive updates 

Market View Industry View Product View 

Access the most current and Access the most current and Access the most current and 
relevant market information. relevant industry information. relevant product information. 


© digitalairlines. All Rights Reserved. | intranet help | feedback 


For more information about Identity Injection policies, see Chapter 8.4, “Identity Injection 


Policies,” on page 810. 


12d Close all sessions of the browser. 
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Our Customers «+ Benefits + IT Services Employee Search GOP 


4.1 


4.1.1 


Setting Up an Advanced Access 
Manager Configuration 


¢ Section 4.1, “Identity Server Advanced Configuration,” on page 251 

¢ Section 4.2, “Access Gateway Server Advance Configuration,” on page 301 
¢ Section 4.3, “Access Gateway Content Settings,” on page 331 

¢ Section 4.4, “Access Gateway Advanced Options,” on page 338 

¢ Section 4.5, “Analytics Server Configuration,” on page 349 

¢ Section 4.6, “Modifying Configuration Files,” on page 356 


Identity Server Advanced Configuration 


¢ Section 4.1.1, “Managing an Identity Server,” on page 251 

¢ Section 4.1.2, “Editing Server Details,” on page 254 

¢ Section 4.1.3, “Customizing Identity Server,” on page 254 

¢ Section 5.1, “Local Authentication,” on page 359 

¢ Section 5.2.4, “Configuring SAML 2.0,” on page 471 

¢ Section 5.2.5, “Configuring SAML 1.1,” on page 506 

¢ Section 5.2.6, “Configuring Liberty,” on page 509 

e Section 5.2.7, “Configuring Liberty Web Services,” on page 516 

¢ Section 5.2.8, “Configuring WS Federation,” on page 535 

¢ Section 5.2.9, “Configuring WS-Trust Security Token Service,” on page 559 
¢ Section 5.2.10, “Configuring OAuth and OpenID Connect,” on page 581 


Managing an Identity Server 


Identity Servers page is the starting point for managing Identity Servers. Most often, you use this 
page to stop and start servers, and to assign servers to Identity Server configurations. An Identity 
Server cannot operate until you have assigned it to an Identity Server configuration. 

1 Click Devices > Identity Servers. 


2 On the Servers tab, you can perform the following functions by clicking the server's check box, 
then clicking any of the following options: 


New Cluster: Creates a new cluster configuration. See “Creating a Cluster Configuration” on 
page 67. 


Start: Starts the selected server. (See “Restarting Identity Server” on page 253.) 
Stop: Stops the selected server. (See “Restarting Identity Server” on page 253.) 
Refresh: Refreshes the server list. 
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Actions: Enables you to perform the following tasks: 


+ 


Assign to Cluster: Enables you to assign a server to a cluster configuration. See 
“Assigning an Identity Server to a Cluster Configuration” on page 71 for more information. 


Remove from Cluster: Enables you to remove one or more servers from a configuration. 
See “Removing a Server from a Cluster Configuration” on page 74 for more information. 


Delete: Deletes the selected server. 


IMPORTANT: The system does not allow you to delete an Identity Server that is started. 
You must first stop the server, then delete it. This removes the configuration object from the 
configuration store on Administration Console. To remove the server software from the 
machine where it was installed, you must run the uninstall script on the server machine. 


Update Health from Server: Performs a health check for the device. 


Export Configuration: Enables you to export Identity Server configuration to another 
setup. See Section 29.6, “Exporting the Configuration Data,” on page 1140. 


Import Configuration: Enables you to import Identity Server configuration from another 
setup. See Section 29.7.3, “Importing Identity Server Configuration Data,” on page 1142. 


This page also displays links in the following columns: 


Column Description 
Name Lists Identity Server and cluster configuration names. 
Status Lists the status of each configuration. 


Current: Indicates that the server is using the latest configuration data. If you 
change a configuration, the system displays an Update or Update All link. 


Update: A link to update an Identity Server’s configuration data without 
stopping the server. 


Update All: A link displayed for cluster configurations. This lets you update all 
Identity Servers in a cluster to use the latest configuration data, with options to 
include logging and policy settings. 


For more information about the update process, see “Updating an Identity 
Server Configuration” on page 253. 


Health Lists the health of each configuration and each server. 

Alerts Displays the Alerts page, where you can monitor and acknowledge server 
alerts. 

Commands Displays the Command Status page. 

Statistics Displays the Server Statistics page and allows you to view the server statistics. 


See Section 22.1.1, “Monitoring Identity Server Statistics,” on page 1065. 


Configuration Lists Identity Server configuration to which this server belongs. 


Starting and Stopping an Identity Server Through Commands 


Start: To start the server, run one of the following commands: 


è /etc/init.d/novell-idp start 


¢ rcnovell-idp start 


252 Setting Up an Advanced Access Manager Configuration 


4.1.1.1 


4.1.1.2 


Stop: To stop the server, run one of the following commands: 


¢ /etc/init.d/novell-idp stop 


+ rcnovell-idp stop 


Updating an Identity Server Configuration 


Whenever you change an Identity Server configuration, the system prompts you to update the 
configuration. An Update Servers status is displayed under the Status column on the Servers page. 
You must click Update Servers to update the configuration so that your changes take effect. 


When you click this link, it sends a reconfigure command to all servers that use the configuration. The 
servers then begin the reconfiguration process. This process occurs without interruption of service to 
users who are currently logged in. 


When you update a configuration, the system blocks inbound requests until the update is complete. 
The server checks for any current requests being processed. If there are such requests in process, 
the server waits five seconds and tests again. This process is repeated three times, waiting up to 
fifteen seconds for these requests to be serviced and cleared out. After this period of time, the update 
process begins. Any remaining requests might have errors. 


During the update process, all settings are reloaded with the exception of the base URL. In most 
cases, user authentications are preserved; however, there are conditions during which some 
sessions are automatically timed out. These conditions are: 


+ A user logged in via an authentication contract that is no longer valid. This occurs if an 
administrator removes a contract or changes the URI that is used to identify it. 


+ A user logged in to a user store that is no longer valid. This occurs if you remove a user store or 
change its type. Changing the LDAP address to a different directory is not recommended, 
because the system does not detect the change. 


+ A user received authentication from an identity provider that is no longer trusted. This occurs if 
you remove a trusted identity provider or if the metadata for the provider changed. 


Additionally, if you remove a service provider from an identity provider, the identity provider removes 
the provided authentication to that service provider. This does not cause a timeout of the session. 


Changes to the SAML and Liberty protocol profiles can result in the trusted provider having outdated 
metadata for Identity Server being reconfigured. This necessitates an update at the other provider 
and might cause unexpected behavior until that occurs. 
1 Click Devices > Identity Servers. 
2 Click Update or Update All. 
These options are only available when you have made changes that require a server update. 


Restarting Identity Server 


Starting and stopping an Identity Server terminates active user sessions. These users receive a 
prompt to log in again unless you have configured session failover (see “Configuring Session 
Failover” on page 72). 

1 Click Devices > Identity Servers, then select Identity Server to stop. 

2 Click Stop. 

3 Wait for the Command Status to change from Pending to Complete. 

4 Select Identity Server, then click Start. 
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5 When the Command Status changes to Complete, click Refresh. 
The status icon of Identity Server must turn green. 


4.1.2 Editing Server Details 


4.1.3 


4.1.3.1 


You can edit server details, such as the server name and port. You can also access the other server 
management tabs from this page. 

1 Click Devices > Identity Servers, then click the server name. 

2 To edit the information, click Edit. 

3 Modify the following fields as necessary: 


Name: The name of Identity Server. Names must be alphanumeric and can include spaces, 
hyphens, and underscores. 


Management IP Address: The IP address of Identity Server. Changing server IP addresses is 
not recommended and causes the server to stop reporting. See Section 2.4, “Changing the IP 
Address of Access Manager Devices,” on page 51. 


Port: Identity Server port used for management. 
Location: The location of Identity Server. 
Description: A description of Identity Server. 

4 To save your changes, click OK. Otherwise, click Cancel. 


Customizing Identity Server 


You can customize login page, logout page, and error messages of Identity Server user portal. 
This section includes the following topics: 

¢ Section 4.1.3.1, “Getting Started,” on page 254 

¢ Section 4.1.3.2, “Customizing Identity Server Login Page,” on page 256 

¢ Section 4.1.3.3, “Customizing Identity Server Logout Page,” on page 272 

¢ Section 4.1.3.4, “Customizing Identity Server Messages,” on page 274 

¢ Section 4.1.3.5, “Maintaining Customized Identity Server,” on page 278 

¢ Section 4.1.3.6, “Sample Custom Login Pages,” on page 279 


Getting Started 


The default user portal is different from Access Manager 4.2 or later. If you have customized the 
legacy user portal, you can retain the customized JSP pages. 


To understand the differences between the two portal pages, see Section 5.1.14, “Managing Direct 
Access to Identity Server,” on page 424. 


To change simple aspects of the default user portal page see, Section 7.8, “Changing the Branding of 
the User Portal Page,” on page 706. 


This section includes the following topics: 


e “Customizing JSP Files” on page 255 
+ “Enabling the AppMark Portal Landing Page in Old Customized JSP Files” on page 255 
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¢ “Enabling reCAPTCHA in Login Page” on page 255 
+ “Enabling Impersonation in Login Page” on page 256 


Customizing JSP Files 


1 Access the /opt/novell/nids/lib/webapp/jsp folder. There might or might not be multiple 
versions of a *.jsp file. 


2 Any file that has *_legacy.jsp in the file name, add your customization to that file. For example, 
if there is a nidp.jsp file and a nidp_legacy.jsp, add your customization to the 
nidp_legacy.jsp file. Make no changes to the nidp. jsp. 


3 If there is only one instance of a*.jsp file, add your customization to that file. For example, if 
there is only a IdentityEditor.jsp file, add your customization to the IdentityEditor.jsp 
file. 


4 Create the /opt/novell/nids/lib/webapp/WEB- INF/legacy folder. 


NOTE: For more information, see “Maintaining Customized JSP Files for Identity Server” in the NetIQ 
Access Manager 4.3 Installation and Upgrade Guide. 


Enabling the AppMark Portal Landing Page in Old Customized JSP Files 


Access the /opt/novell/nids/1ib/webapp/jsp folder and make the following changes in 
nidp_legacy.jsp and content_legacy. jsp files: 


1 Both nidp_leagcy.jsp and content_legacy.jsp contain the ContentHandler object that is 
accessed in the top Java section. Access ContentHandler by using the following method: 
ContentHandler handler = new ContentHandler (request, response); 


2 Add the following Java line to determine if the control should be transferred to the AppMark 
Portal Landing page: 


boolean bGotoAlternateLandingPageUrl = handler.gotoAlternateLandingPageUr1(); 


3 Ifthe handler .gotoAlternateLandingPageUr1(); method returns “true”, redirect the control to 
the AppMark Portal Landing page by using JavaScript. 


3a Find the first <script> </script> HTML tag pair in both files. 
3b In the JavaScript section, add the following lines inside the script tag: 


<% if (bGotoAlternateLandingPageUrl) { %> 
document.location = "<%=handler.getAlternateLandingPageUr1( )%>"; 
<% } %> 


Enabling reCAPTCHA in Login Page 


Access the /opt/novell/nids/1lib/webapp/jsp folder and include login_captcha. jsp in the 
following files: login_legacy.jsp and login_latest.jsp. 


For example: In the following sample code, include login_captcha. jsp as indicated: 
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4.1.3.2 


<div id="namepassword" class="content login-page" style="margin: 25px; display: 
block; "> 
<div class="signin-div"> 
<div class="input-signin-username"><input type="text" 
id="Ecom_User_ID" name="Ecom_User_ID" value="<%=uname%>"" tabindex="1" 
placeholder="<%=handler .getResource(JSPResDesc .USERNAME_UNDER_LABEL )%>"></div> 
</div> 
<div class="signin-div"> 
<div class="input-signin-password"><input type="password" 
id="Ecom_Password" name="Ecom_Password" tabindex="2" 
placeholder="<%=handler .getResource(JSPResDesc .PASSWORD_UNDER_LABEL )%>"></div> 
</div> 
<%@ include file="login_captcha.jsp" %> 
<div class="closure-but signin-div"> 
<span class="nam-signin-but action-but" name="loginButton2" 
id="loginButton2" tabindex="3"><%=strSignIn%></span> 
</div> 
</div> 


Enabling Impersonation in Login Page 


The default User Portal page works with impersonation, but if you have customized Identity Server to 
provide custom login and logout pages for your customers, you must change your customized pages 
for impersonation to work. For more information, see Section 27.5, “Implementing Impersonation in 
Custom Portal Pages,” on page 1125. 


Customizing Identity Server Login Page 


You can create custom login pages that are displayed when the user authenticates to Identity Server. 
There are a multitude of reasons for customizing the login page. You might want to remove the NetIQ 
branding and replace it with your company’s brands. You might need to authenticate users with non- 
default attributes (such as an e-mail address rather than a username). You also might be fronting 
several protected resources with an Access Gateway, and you need to create a unique login page for 
each resource. 


When you customize the login page: 
+ You need to decide on the type of page to use. See “Selecting the Login Page and Modifying It” 
on page 257. 


+ You need to configure Identity Server to display the correct login page. See “Configuring Identity 
Server to Use Custom Login Pages” on page 266. 


+ |f the custom page does not display, you need to discover the cause. See “Troubleshooting Tips 
for Custom Login Pages” on page 271. 


e You need to sanitize the JSP file to prevent XSS attacks. See Section 10.7, “Preventing Cross- 
site Scripting Attacks,” on page 930. 


Modifying the Target of the User Portal: If you want to control the target when users log directly 
into Identity Server, see “Specifying a Target” on page 425. 


Modifying Error Pages: Both Identity Server and Access Gateway return error pages to the user. 
For information about customizing these messages and pages, see the following: 
e “Customizing Identity Server Messages” on page 274 


¢ Section 4.2.9.2, “Customizing Error Messages and Error Pages on Access Gateway,” on 
page 325. 
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Selecting the Login Page and Modifying It 


You must be familiar with customizing JSP files to create a customized login page. You can use any 
of the following methods to produce the page: 


¢ If you only need to customize the credentials (for example, prompt the user for an e-mail address 
rather than a name), you can make most of the modifications in Administration Console. You 
need to add some properties to a method, create a contract from that method, and modify the 
prompt inthe login.jsp file. For configuration information, see “Customizing the Default Login 
Page to Prompt for Different Credentials” on page 257. 


¢ If you want to maintain the features of the 4.0 page and use its authentication cards but you want 
to remove the NetIQ branding, you need to modify the nidp_legacy. jsp file. The 
nidp_legacy.jsp file uses iframes, so the devices that your users use for authentication must 
also support iframes. For configuration information, see “Customizing the nidp.jsp File” on 
page 260. 


+ 


If you don’t need the authentication cards and if the devices that your users use for 
authentication support iframes, you can start with the login. jsp file and customize it. For 
configuration information, see “Modifying the login.jsp File” on page 265. 


NOTE: After you have created customized login pages, you need to back them up before doing an 
upgrade. The upgrade process overrides any custom changes made to JSP files that use the same 
filename as those included with the product. 


During an upgrade, you can select to restore custom login pages, but NetIQ recommends that you 
have your own backup of any customized files. 


Customizing the Default Login Page to Prompt for Different Credentials 


This section explains how to prompt the users for an identifier other than the user's name. Figure 4-1 
displays the default login page with the username prompt. 


Figure 4-1 Modifying the Credential Prompts 


lE] NetIQ Access Manager 


Authentication 


Username: || 


Password: | 


Authentication Cards 


>_> a _ 
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This section explains how to modify the content of the login. jsp file. If you want to modify other 
aspects of this page, you need to select one of the other methods. 


The instructions below explain how to create a method that sets up the appropriate query so that the 
user can be found in the user store with an identifier other than the username (the cn attribute). The 
instructions then explain how to create a contract that uses this method and how to modify the 
login. jsp page so that it prompts for the appropriate identifier such as an email address instead of a 
username. 
1 Create a method with the appropriate query: 

1a Click Devices > Identity Servers > Edit > Local > Methods. 

1b Click New, then specify a Display Name. 

1c In the drop-down menu for classes, select a class that is a username/password class. 


1d Leave the Identifies User option enabled, and configure the user store option according to 
your needs. 


1e In the Properties section, click New, then specify the following values: 
Property Name: Query 
Property Value: (&(objectclass=person) (mail=%Ecom_User_ID%) ) 


This property is defined so that it queries the user store for the attribute you want to use 
rather than the cn attribute (in this case, the mail attribute of the person class). The 
%Ecom_User_ID% variable is the default variable name on the login page. You can change 
this to %EMail_Address% if you also change the value in your custom login page. 


For more information about how to use this property, see “Query Property” on page 373. 
1f In the Properties section, click New, then specify the following values: 

Property Name: JSP 

Property Value: <filename> 


Replace <filename> with the name of the custom login. jsp page you are going to create 
so that the page prompts the user for an e-mail address rather than a username. This must 
be the filename without the JSP extension. For example, if you name your file 
email_login.jsp, then you would specify email_login for the property value. 


1g Click OK. 
2 Create a contract that uses this method: 
2a Click Contracts > New. 
2b Select the method you just created. 
2c Configure the other options to fit your requirements. 


For information about configuring the other options for a contract, see Section 5.1.4, 
“Configuring Authentication Contracts,” on page 379. 


2d Click OK. 
3 Update Identity Server. 


4 Copy the login. jsp file and rename it. The JSP files are located on Identity Server in the 
following directory: 


Linux: /opt/novell/nids/lib/webapp/jsp 
Windows Server 2012 R2: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 


5 (Conditional) If you modified the %Ecom_User_ID% variable, find the string in the file and replace 
it with your variable. 
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6 (Conditional) If you need to support only one language, modify the prompt in the login. jsp file: 
6a Find the following string in the file: 


<label><%=handler .getResource(JSPResDesc .USERNAME )%></label> 
6b Replace it with the string you want, for example: 
<label>Email Address:</label> 


6c Copy the modified file to each Identity Server in the cluster. 
6d Back up your customized file. 


7 (Conditional) If you need to localize the prompt for multiple languages, create a custom message 
properties file for the login prompt. (For more information about how to create a custom message 
properties file, see “Customizing Messages” on page 274.) 


The following steps assume you want to change the username prompt to an e-mail address 
prompt. 


7a Find the following definition in the com/novell/nidp/resource/jsp directory of the 
unzipped nidp. jar file. 


JSP .50=Username: 


7b Add this definition to your custom properties file and modify it so that it prompts the user for 
an e-mail address. 


JSP.50=Email Address: 


7c Translate the value and add this entry to your localized custom properties files. 


7d Copy the customized properties files to the WEB- INF/classes directory of each Identity 
Server in the cluster. 


7e Restart Tomcat on each Identity Server using one of the following commands: 
Linux Identity Server: Enter the following command: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
Windows Identity Server: Enter the following commands: 
net stop Tomcat7 net start Tomcat7 


8 To view a sample custom page with these modifications, see “Modified login.jsp File for 
Credential Prompts” on page 285. 
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Customizing the nidp.jsp File 


Figure 4-2 displays the default login page provided by Access Manager. Multiple JSPs are used to 
create the page. 


Figure 4-2 The JSPs That Create the Login Page 


nidp.jsp menus.jsp login.jsp content.jsp 


fc] Novell Access Manager 


Authentication 
User Legin | 


You can use the nidp_legacy.jsp file to customize the header with the Access Manager product 
name and the NetIQ logo. The menus. jsp file controls the Authentication and User Login tabs. The 
login. jsp file controls the credential frame with username and password. The content. jsp file 
controls what is displayed on the page, including the available authentication cards. 


The following sections explain how to modify the login page that these JSPs create: 


+ Rebranding the Header 

¢ Customizing the Card Display 

+ Customizing the Credential Frame 

+ Customizing the nidp.jsp File to Customize Error Message 


Rebranding the Header 
1 Copy the nidp_legacy.jsp file and rename it. The JSP files are located on Identity Server in the 
following directory: 
Linux: /opt/novell/nids/lib/webapp/jsp 
Windows Server 2012 R2: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 
2 Replace the header title that appears in the top frame (“NetIQ Access Manager’ in Figure 4-2): 
2a Locate the following string at the top of the file. 


String hdrTitle = handler.getResource(JSPResDesc.PRODUCT) ; 
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2b 


Replace the value with the title you want to appear. For example: 
String hdrTitle = "My Company"; 


Ensure that to enclose your title value with double quotes. 


3 Replace the window title that appears in the browser title bar: 


3a 


3b 


Locate the following line that appears between the <head></head> tags: 
<title><%=handler .getResource(JSPResDesc. TITLE)%></title>; 


Replace the content between the <title> and </title> tags with the title you want to 
appear. For example: 


<title>My Company</title>; 


4 Replace the Access Manager logo on the left of the header (see Figure 4-1): 


4a 


4b 


4c 


Locate the following string: 
String hdrImage = "AMHeader_image.png"; 


Replace the value in the quotes with the path and the filename of the image you want to 
use. 


For example, if you created a /custom_images directory in the images directory, the 
hdriImage string would have a value similar to the following: 


String hdrImage = "/custom_images/myapp.png" 
NOTE: Mobile login page customization is only supported in mobile / hand-held Web 


browsers that support CSS 3.0 specifications. If the browser does not support CSS 3.0 
specification, the default logo and header of the normal window is displayed in smaller size. 


To customize the logo for a mobile view, create a new logo and name it logo_new. gif. The 
recommended size of the logo is 40x40 pixels. 


5 Replace the NetIQ logo on the right of the header (see Figure 4-2): 


5a 


5b 


Locate the following string: 
String hdrLogo = "AMHeader_logo.png"; 


Replace the value of the hdrLogo string with the path and the filename of the image you 
want to use. 

For example, if you created a /custom_images directory in the images directory, the 
hdrLogo string would have a value similar to the following: 


String hdrLogo = "/custom_images/companylogo.png"; 


6 To change the background image for the header (which allows for variable sizing of the page): 


6a 


6b 


Locate the following string: 
String hdrBgndImg = "AMHeader_background.png"; 


Replace the value of the hdrBgndInmg string with the path and the filename of the image you 
want to use. You can use a color or an image that can be repeated. The style is set to repeat 
it from left to right as the window expands. 


For example, if you created a /custom_images directory in the images directory, the 
hdrBgndImg string would have a value similar to the following: 
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String hdrBgndImg = "/custom_images/mybackground.png"; 
6c To customize the header for a mobile view, create a new header and name it 
banner_new.gif. The recommended size of the banner is 40x800 pixels. 


7 If your custom images or title do not appear in the header where you want them, you need to 
modify the style section. 


7a Locate the following lines: 


#header { background-image: url(<%= handler.getImage(hdrBgndiImg, false)%>) ; 
background-repeat: repeat-x; } 


#logo { position: absolute; top: Opx; right: Opx; } 


#title { position: absolute; font-size: 1.2em; color: white; top: 13px; 
left: 55px; } 
7b Modify the top, left, and right values. 


8 To change the background colors on the page, modify the color values in the <style> section of 
the <head> element. 


9 If you need to create multiple custom login pages, repeat Step 1 through Step 8. 
10 Copy the custom login pages and the images they require to each Identity Server in the cluster. 
11 Continue with one of the following tasks: 


+ To modify what appears in the credential frame, continue with “Customizing the Credential 
Frame” on page 263. 


¢ To control the cards displayed in the Authentication Cards section, see “Customizing the 
Card Display” on page 262. 


+ To configure Identity Server to use your custom pages, see “Adding Logic to the main.jsp 
File” on page 267. 


+ To view a sample custom page with these modifications, see “Custom nidp.jsp File with 
Custom Credentials” on page 287. 


Customizing the Card Display 


The easiest method to control what appears in the Authentication Cards section is not by modifying 
the content. jsp file. It is by using the Show Card option that appears on the definition of each card. 
If this option is not selected, the card does not appear in the Authentication Cards section. Each 
contract has an associated card. For information about modifying the card options, see Section 5.1.4, 
“Configuring Authentication Contracts,” on page 379. 


Continue with one of the following: 


+ To modify what appears in the credential frame, continue with “Customizing the Credential 
Frame” on page 263 


¢ To configure Identity Server to use your custom pages, see “Adding Logic to the main.jsp File” on 
page 267. 
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Customizing the Credential Frame 


The most common reason for modifying the login. jsp page is to prompt the users for an identifier 
other than the user’s name. To do this, you need to create a method that sets up the appropriate 
query so that the user can be found in the user store with an identifier other than the username. You 
then need to create a contract that uses this method. You also need to modify the prompt in the 
login. jsp page to match the identifier you are prompting for. 


1 Create a method with the appropriate query: 


la 
1b 
1c 
1d 


1e 


1f 


1g 


Click Devices > Identity Servers > Edit > Local > Methods. 
Click New, then specify a Display Name. 
In the drop-down menu for classes, select a class that is a username/password class. 


Leave the Identifies User option enabled, and configure the user store option according to 
your needs. 


In the Properties section, click New, then specify the following values: 
Property Name: Query 
Property Value: (&(objectclass=person) (mail=%Ecom_User_ID%) ) 


This property is defined so that it queries the user store for the attribute you want to use 
rather than the cn attribute (in this case, the mail attribute of the person class). Change 
mail to the name of the attribute in your user store that you want to use for the user 
identifier. 

The %Ecom_User_ID% variable is the default variable name on the login page. You can 
change this to something like %EMail_Address% if you also change the value in your 
custom login page. 


For more information about how to use this property, see “Query Property” on page 373. 
In the Properties section, click New, then specify the following values: 

Property Name: JSP 

Property Value: <filename> 


Replace <filename> with the name of the custom login. jsp page you are going to create 
so that the page prompts the user for an e-mail address rather than a username. This must 
be the filename without the JSP extension. For example, if you name your file 
email_login.jsp, then you would specify email_login for the property value. 


Click OK. 


2 Create a contract that uses this method: 


2a 
2b 
2c 


2d 


Click Contracts > New. 
Select the method you just created. 
Configure the other options to fit your requirements. 


If you are creating multiple custom login pages with customized credentials, you might want 
to use the URI to hint at which custom login. jsp file is used with which custom 
nidp_legacy.jsp file. For example, the following URI values have the filename of the login 
page followed by the name of the custom nidp_legacy. jsp page: 


logini/custom1 
login2/custom2 
login3/custom3 


For information about configuring the other options for a contract, see Section 5.1.4, 
“Configuring Authentication Contracts,” on page 379. 


Update Identity Server. 
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3 Copy the login. jsp file and rename it. The JSP files are located on Identity Server in the 
following directory: 


Linux: /opt/novell/nids/lib/webapp/jsp 
Windows Server 2012 R2: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 


4 (Conditional) If you modified the %Ecom_User_ID% variable, find the string in the file and replace 
it with your variable. 


5 (Conditional) If you need to support only one language, modify the prompt in the login. jsp file: 
5a Find the following string in the file: 


<label><%=handler .getResource(JSPResDesc .USERNAME )%></label> 
5b Replace it with the string you want, for example: 
<label>Email Address:</label> 


5c Copy the modified file to each Identity Server in the cluster. 
5d Back up your customized file. 


6 (Conditional) If you need to localize the prompt for multiple languages, create a custom message 
properties file for the login prompt. (For more information about how to create a custom message 
properties file, see “Customizing Messages” on page 274.) 


The following steps assume you want to change the username prompt to an e-mail address 
prompt. 


6a Find the following definition in the com/novell/nidp/resource/jsp directory of the 
unzipped nidp. jar file. 


JSP .50=Username: 


6b Add this definition to your custom properties file and modify it so that it prompts the user for 
an e-mail address. 


JSP.50=Email Address: 


6c Translate the value and add this entry to your localized custom properties files. 


6d Copy the customized properties files to the WEB- INF/classes directory of each Identity 
Server in the cluster. 


6e Restart each Identity Server using one of the following commands: 
Linux Identity Server: Enter one of the following command: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
Windows Identity Server: Enter the following commands: 
net stop Tomcat7 net start Tomcat7 


7 To view a sample custom page with these modifications, see “Custom nidp.jsp File with Custom 
Credentials” on page 287. 


8 To specify which customized nidp_legacy.jsp to display with the contract, you must modify the 
main. jsp file. Continue with “Adding Logic to the main.jsp File” on page 267. 
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Customizing the nidp.jsp File to Customize Error Message 


Identity Server publishes a generic error message for error code during SAML failure such as request 
denied or Invalid Name ID Policy and so on. You can customize the NIDP jsp file available at /opt/ 


novell/nids/lib/webapp/jsp and write an appropriate error message for either redirection or to 


inform the user about the issue with an appropriate message. Perform the following steps to 
customize error message. 


NOTE: In the following example the specified code snippet is for simulating InvalidNamelDPolicy 


error for SAML 2.0. 


1 Generate an error condition with for example, Invalid Name ID Policy. 


2 Customized the nidp.jsp file and add the following code for redirection. 


com.novell.nidp.ui.MenuHandler redirectMenuHandler ; 
com.novell.nidp.NIDPMessage redirectMessage; 
String redirectCause; 


redirectMenuHandler = new MenuHandler(request, response); 

redirectMessage = redirectMenuHandler .getMessage(true); 

if (redirectMessage != null && redirectMessage instanceof 
com.novell.nidp.NIDPError) { 

redirectCause = ((com.novell.nidp.NIDPError) 
redirectMessage) .getNIDPExceptionMsg(); 


System.out.println("************** redirectCause" + redirectCause); 


if (redirectCause != null && 
redirectCause. indexOf("InvalidNameIDPolicy") != -1) { 
response. sendRedirect("http://www.novell.com"); 
return; 
} 


} 


3 Restart Identity Server by using the rcnovell-idp restart command. 


4 Verify that when failure occurs, SAML shows the following message in the authentication 
response. 


<samlp:Status><samlp:StatusCode 
Value="urn:oasis:names:tc:SAML:2.0:status:Responder"><samlp:StatusCode 
Value="urn:oasis:names:tc:SAML:2.0:status: InvalidNameIDPolicy"/></ 
samlp:StatusCode> 


Due to customized nidp_legacy.jsp file, SAML redirects to specified location. 


5 Rerun the failure and verify that instead of displaying 300101008, nidp page redirects to the 


specified www.novell.com location. 


Modifying the login.jsp File 


The login. jsp file gives you just the credential frame with the login prompts in an iframe. It has no 
branding header. If you use this page, you are responsible for writing the HTML code for the header 


and the branding. 


1 Copy the login. jsp file and rename it. The JSP files are located on Identity Server in the 


following directory: 
Linux: /opt/novell/nids/lib/webapp/jsp 


Windows Server 2012 R2: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 


2 Add the custom branding and any other content you require to the file. 
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To modify the credentials, see “Customizing the Credential Frame” on page 263. 
Repeat Step 1 through Step 3 for each resource that requires unique branding. 


3 
4 
5 Copy the files to each Identity Server in the cluster. 
6 Back up your customized files. 

7 


(Optional) To view a sample custom page with these modifications, see “Custom 3.2.x or Later 
login.jsp File” on page 294. 


8 Continue with “Using Properties to Specify the Login Page” on page 266. 


Configuring Identity Server to Use Custom Login Pages 


There are two ways to configure Identity Server to use a custom login page. You can use properties 
or you can modify the main. jsp file. Which method you can use depends upon your modifications. 


+ You can use properties if you created your custom page from the 3.2 or later login. jsp page. 
See “Using Properties to Specify the Login Page” on page 266. 


+ If you created your custom page from the nidp_legacy.jsp file, you cannot use properties to 
specify the main custom page for authentication. You must modify the main. jsp file. See 
“Adding Logic to the main.jsp File” on page 267. 


Using Properties to Specify the Login Page 


For each resource that needs a unique login page, you need to create an authentication method and 
add the JSP and MainJSP properties to the method. You then need to create a contract for each 
method. 


The following steps assume that the custom login page is called custom1. jsp. 


1 Create a method for a custom login page: 
1a Click Devices > Identity Servers > Edit > Local > Methods. 
1b Select one of the following actions: 


+ If you have create a method for a Query property to be used with your custom login 
page, click the name of the method. 


+ If you didn’t modify the credentials on the login page, click New, specify a display 
name, select a password class, and configure a user store. 


1c Inthe Properties section, click New, then specify the following: 
Property Name: MainJSP 
Property Value: true 


This property indicates that you want to use a custom login page with this method. It also 
indicates that the custom login page contains the prompts for user credentials. 


Property names and values are case sensitive. 
1d Click OK. 


1e (Conditional) If the Properties section does not contain a JSP property, click New, specify 
the following: 


Property Name: JSP 
Property Value: custom1 


The property value for the JSP property is the name of the custom login file without the JSP 
extension. Replace custom1 with the name of your custom login file. This property 
determines which login page is displayed when this method is used. The filename cannot 
contain nidp as part of its name. 
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1f Click OK. 


For more information about setting property values, see “Specifying Common Class 
Properties” on page 373. 


1g (Conditional) If you created multiple custom login pages, repeat Step 1b through Step 1e for 
each page. 


2 For each method that you modified for a custom login page, create a contract: 
2a Click Contracts, then click New. 


2b Fill in the fields to fit the needs of the resource, but ensure that to assign the custom method 
as the method for the contract. 


2c Click Next, configure a card for the contract, then click Finish. 
3 Update Identity Server. 


4 For each resource that you have created a custom login page, assign that resource to use the 
contract that is configured to display the appropriate login page: 


4a Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service Name] 
> Protected Resources. 


4b For each protected resource that you have created a custom contract for, select the 
protected resource, then configure it to use the custom contract. 


5 Update Access Gateway. 
6 (Conditional) If the custom page does not display correctly, see “Troubleshooting Tips for 
Custom Login Pages” on page 271. 
Adding Logic to the main.jsp File 


You can modify the main. jsp file and use the contract URI to specify the login page to display. 
Identity Server must be running 3.2 or later to use this feature. Be aware of the following: 


+ The main.jsp file cannot be renamed, so any modifications you make to this file can be lost 
whenever you upgrade Identity Server. During the upgrade, you must select to restore custom 
files or you must restore your modified file after the upgrade. If this is the only JSP file that you 
modified that uses an Identity Server name, it is probably best to manually restore this file after 
an upgrade. 


¢ Modifying the main. jsp file requires knowledge of JSP programming and if/else statements. 
Modifying the main. jsp file allows you to have the following type of configuration: 
+ You can create multiple customized nidp_legacy.jsp pages. For example: custom1.jsp, 
custom2.jsp, and custom3.jsp. 


+ You can create multiple customized login. jsp pages that request different login credentials. 
For example: 


login1.jsp: Configured to request username and password. 

login2.jsp: Configured to request username, email, and password. 

login3.jsp: Configured to request email and password. 
With this type of configuration, you must create three different authentication contracts with an 
authentication method with a JSP property defined for each of them. These contracts require the 


types of values listed in the table below. The URI is defined so that it reflects the custom login. jsp 
and the custom nidp_legacy.jps that are used by the contract. 
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Contract Configuration Details 


Contract1 URI 
Method1 

Contract2 URI 
Method2 

Contract3 URI 
Method3 


logini/custom1 

Configured with the following JSP property: 
Property Name: JSP 

Property Value: login1 


This method does not need a query property unless 
you are using an attribute other than the cn attribute 
for the username. 


login2/custom2 

Configured with the following two properties: 
Property Name: JSP 

Property Value: login2 

Property Name: Query 

Property Value: 


(&(objectclass=person) (mail=%Ecom_User_ID 


%))) 


login3/custom3 

Configured with the following two properties: 
Property Name: JSP 

Property Value: login3 

Property Name: Query 

Property Value: 


(&(objectclass=person) (mail=%Ecom_User_ID 
%) ) 


The following procedure explains how to configure Access Manager to display these custom login 


pages with custom credentials. 


1 Create a unique method for each custom login. jps file: 


1a Click Devices > Identity Servers > Edit > Local > Methods. 


1b Click New, then configure the following fields: 


Display name: Specify a name for the method. You might want to use a name that 
indicates which login page is assigned to this method. 


Class: Select a name/password class. 


Configure the other fields to match your requirements. 


1c Inthe Properties section, add a Query property if the page uses custom credentials. 


For example, to add an email address to the login prompts, add the following property: 


Property Name: Query 


Property Value: (&(objectclass=person) (mail=%Ecom_User_ID%) ) 


Setting Up an Advanced Access Manager Configuration 


If you are creating a method for Contract 1 in the example above (which prompts for a 
username and password), you do not need to add a query property unless you are using an 
attribute other than the cn attribute for the username. 


1d In the Properties section, add a JSP property to specify which login. jsp file to use with 
this method. 


For example: 
Property Name: JSP 
Property Value: login2 
le Click Finish. 
1 


-h 


If you have created more than one custom login. jsp file, repeat Step 1b through Step 1e 
for each page. 


To configure the scenario described in this section, repeat these steps for three login pages. 
2 Create a unique contract URI: 
2a Click Contracts. 
2b Click New, then configure the following fields: 


Display name: Specify a name for the contract. You might want to use a name that 
indicates which login page is assigned to this contract. 


URI: Specify a value that uniquely identifies the contract from all other contracts. No spaces 
can exist in the URI field. You might want to use a name that indicates the custom login 
page and custom credential page, such as login1/custom1. 


Methods and Available Methods: Select the authentication method you configured in 
Step 1. 


2c Configure the other fields to meet your network requirements, then click Next. 
2d Configure the authentication card, then click Finish. 


2e (Conditional) If you have created multiple custom login pages, repeat Step 2b through 
Step 2d for each page. 


To configure the scenario described in this section, repeat these steps for /login2/custom2 
and /login3/custom3. 


2f Click OK, then update Identity Server. 
3 Modify the main. jsp file: 

3a Open the main. jsp file. The file is located in the following directory: 
Linux: /opt/novell/nids/lib/webapp/jsp 
Windows Server 2012 R2: \Program Files (x86)\Novell\Tomcat \webapps\nidp 
\jsp 

3b Near the top of the file, add the following line: 
String strContractURI = hand.getContractURI(); 


This sets the strContractURI variable to the value of the contract URI that is being used 
for authentication. These lines must look similar to the following: 
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<% 
ContentHandler hand = new ContentHandler(request, response); 
String strContractURI = hand.getContractURI(); 


// Is there a JSP defined on a class definition or a method 
// definition that must be displayed as the main jsp here? 
if (handler.contractDefinesMainJSP() ) 


%> 


3c After the if statement, add an else if statement for each contract URI you have created. 


For example: 


<% } 
else if(strContractURI != null && strContractURI.equals("logini/custom1") ) 
{ 


%> 
<%@ include file="Ccustom1.jsp" %> 


<% } 
else if(strContractURI != null && strContractURI.equals("login2/custom2") ) 
{ 


%> 
<%@ include file="Custom2.jsp" %> 


<% } 
else if(strContractURI != null && strContractURI.equals("login3/custom3") ) 
{ 


%> 
<%@ include file="custom3.jsp" %> 


These else if statements set up three contracts for customized login pages: 


¢ The first else if statement specifies the URI of the login1 contract and configures it to 
display the custom1. jsp page for authentication. 


+ The second else if statement specifies the URI of the login2 contract and configures 
it to display the custom2.jsp page for authentication. 


+ The third else if statement specifies the URI of the login3 contract and configures it 
to display the custom3.jsp page for authentication. 


Your file must look similar to the following: 


<%@ page language="java" %> 

<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%> 
<%@ page import="com.novell.nidp.*" %> 

<%@ page import="com.novell.nidp.resource.jsp.*" %> 

<%@ page import="com.novell.nidp.ui.*" %> 

<%@ page import="com.novell.nidp.common.util.*" %> 

<%@ page import="com.novell.nidp.liberty.wsf.idsis.apservice.schema.*" %> 


<% 
ContentHandler hand = new ContentHandler(request, response); 
String strContractURI = hand.getContractURI(); 


// Is there a JSP defined on a class definition 
// or a method definition that must be displayed 
// as the main jsp here? 

if (hand.contractDefinesMainJSP()) 


%> 
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<%@ include file="mainRedirect.jsp" %> 
<% } 
else if(strContractURI != null && strContractURI.equals("login1/ 
custom1") ) 


%> 
<%@ include file="Ccustom1.jsp" %> 


<% } 
else if(strContractURI != null && strContractURI.equals("login2/custom2") ) 
{ 


%> 
<%@ include file="custom2.jsp" %> 


else if(strContractURI != null && strContractURI.equals("login3/custom3")) 
{ 


%> 
<%@ include file="custom3.jsp" %> 


<% } // This is the jsp used by default 
else 
{ 
%> 
<%@ include file="nidp.jsp" %> 
<% } %> 


3d Copy the modified main. jsp file to each Identity Server in your cluster. 


4 Back up your customized files. 


5 For each resource that you have created a custom login page for, assign that resource to use the 


contract that is configured to display the appropriate login page: 


5a Click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Proxy Service Name] 


> Protected Resources. 


5b For each protected resource that you have created a custom contract for, select the 


protected resource, then configure it to use the custom contract. 


5c Update Access Gateway. 


6 (Conditional) If the custom page does not display correctly, see “Troubleshooting Tips for 


Custom Login Pages” on page 271. 


Troubleshooting Tips for Custom Login Pages 


If your custom login page does not display or generates an error message, use the following 
procedure to discover the root cause: 


1 


Set the Application option of Component File Logger Levels to debug, update Identity Server, 
attempt to log in, then view the log file. 


Check for Unable to Compile errors in the log file. If your custom page does not compile, a blank 
page is displayed. 


If you receive an Unable to Find File error, verify the value of the JSP property. Ensure that the 
value does not contain the JSP extension as part of the filename. 


If you see pages that you have deleted or pages where your modifications have not been 
implemented: 


3a Open the new custom file with a text editor to ensure it has a newer date than the compiled 


file. 
If this does not solve the problem, continue with Step 3b. 
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3b Delete the nidp directory in the Tomcat work directory on each Identity Server to recompile 
JSP pages. 


Linux: /opt/novell/nam/idp/work/Catalina/localhosts/nidp 


Windows Server 2012 R2: \Program Files (x86)\Novell\Tomcat\work\Catalina 
\localhosts\nidp 


3c Restart Tomcat on each Identity Server. 


Customizing Identity Server Logout Page 


You can also use the following methods to modify Identity Server logout page: 


¢ “Rebranding the Logout Page” on page 272 

+ “Replacing the Logout Page with a Custom Page” on page 272 

¢ “Configuring for Local Rather Than Global Logout” on page 273 

e “Customizing Logout Pages to Redirect Based on Parameters” on page 274 


To customize the logout page when the user logs out of an Access Gateway protected resource, see 
Section 4.2.9.3, “Customizing Logout Requests,” on page 328. When you have both Liberty and 
SAML 2.0 sessions running on Identity Server and you log out of Access Gateway, the 
logoutsuccess_legacy.jsp page is not executed with the customization you have made to the 
logout page. For information about the workaround, see “Logging Out of Sessions of Access 
Gateway and SAML Connectors when Branding Exists in the Customized Logout Page” on page 330. 


NOTE: After customizing a JSP file, you need to sanitize the JSP file to prevent XSS attacks. See, 
Section 10.7, “Preventing Cross-site Scripting Attacks,” on page 930. 


Rebranding the Logout Page 


The branding in the header of the logout page is controlled by the branding of the nidp_legacy.jsp 
file. If you have modified this file for a customized login, the same branding appears in the logout 
page. For information about how to modify nidp_legacy. jsp for logos, titles, and colors, see 
“Rebranding the Header” on page 260. 


IMPORTANT: Save a copy of your modified nidp_legacy. jsp file. Every time you upgrade your 
Identity Server, you need to restore this file. 


Replacing the Logout Page with a Custom Page 


You can create your own logout page and configure Identity Server to use it. To do this, you need to 
modify the logoutSuccess_legacy.jsp file on Identity Server. It is located in the following directory: 


Linux: /opt/novell/nids/1lib/webapp/jsp 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 


The logoutSuccess_legacy.jsp file is called in a frame from the nidp_legacy.jsp file. You can 
modify the file to display what you want or you can modify it to redirect the user to your custom page. 
One way to provide redirection is to replace the information in the <body> element of the file with 
something similar to the following: 
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<body> 
<script language="JavaScript"> 
top. location. href='http://<hostname/path>'; 
</script> 
</body> 


Replace the <hostname/path> string with the location of your customized logout page. 


IMPORTANT: Save a copy of your modified logoutSuccess_legacy.jsp file. Every time you 
upgrade your Identity Server, you will need to restore this file. 


Configuring for Local Rather Than Global Logout 


By default, when Identity Server receives a logout request, Identity Server logs the user out of any 
identity providers and service providers to which the user has authenticated. If you want to modify this 
behavior so that the logout request logs the user out of just Identity Server and leaves the user 
authenticated to identity providers and service providers, you need to add the following query string to 
the logout URL: 


?local=true 
The logout URL has the following format: 
<Base_URL>/app/logout 


Replace <Base_URL> with the base URL of your Identity Server. If the base URL of your Identity 
Server was https://hhb1.provo.novell.com:8443/nidp, your local logout URL would be the 
following: 


https://hhb1.provo.novell.com:8443/nidp/app/logout?local=true 
To modify the logout . jsp file so that it performs a local logout: 


1 At Identity Server, open the logout.jsp file. 

Linux: /opt/novell/nids/lib/webapp/jsp 

Windows Server 2012: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 
2 Find the following line in the file: 


<form method="post" target="_top" action="<%= request.getContextPath() %>/app/ 
logout"> 


3 Tothe /app/logout string, add ?local=true. This modified line must look similar to the 
following: 


<form method="post" target="_top" action="<%= request.getContextPath() %>/app/ 
logout?local=true"> 


4 Save the file. 
5 Copy the file to each Identity Server in the cluster. 
6 Back up this file. 
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Customizing Logout Pages to Redirect Based on Parameters 


You can customize an Identity Server logout page to redirect to URLs based on parameters specified 


in the logoutSuccess_legacy.jsp file. To customize the logoutSuccess_legacy. jsp file to 
redirect to URLs, perform the following steps: 
1 At Identity Server, open the logoutSuccess_legacy. jsp file: 
Linux: /opt/novell/nids/1lib/webapp/jsp 
Windows: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 
2 Add the following as the last line in the logoutSuccess_legacy . jsp file: 
<%out.println("UIHandler-param: " + uh.getLogoutQueryStringParam("test") ) ;%> 
Here test indicates name of the parameter. 
3 Restart Identity Server. 


4 Specify a parameter with the logout URL. For example: https: //www. idp.com:8443/nidp/ 
app/logout?test=NetI1Q. 


The logout page displays UIHandler-param: NetIQ in the logout page. 


Customizing Identity Server Messages 


e “Customizing Messages” on page 274 
¢ “Customizing the Branding of the Error Page” on page 276 


e “Customizing Tooltip Text for Authentication Contracts” on page 278 


NOTE: After customizing a JSP file, you need to sanitize the JSP file to prevent XSS attacks. See, 
Section 10.7, “Preventing Cross-site Scripting Attacks,” on page 930. 


Customizing Messages 


1 To customize the error pages, determine whether you need one custom file or multiple files: 


+ If you do not need to support multiple languages, you can create one custom file for all your 
customized messages. 


+ If you need to support multiple languages, you need to create a custom file for each 
language you want to customize. 


2 Create the custom properties file and name it: 
To support one language, name the file nidp_custom_resources. properties. 


To support multiple languages, create a nidp_custom_resources_<le_cy>.properties file for 
each supported language. Replace </e_cy> with the standard convention for Java Resource 
Bundles for the language or the language and country. For example: 


nidp_custom_resources_en_US.properties 
nidp_custom_resources_fr.properties 
nidp_custom_resources_es.properties 


If you want to support a custom messages for a language and a country and for just the 
language, you must create two files. For example: 


nidp_custom_resources_es_VE.properties 
nidp_custom_resources_es.properties 


3 Copy the nidp. jar file to a working area. This file is located in the following directory: 
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Linux: /opt/novell/nids/1ib/webapp/WEB- INF/1ib 


Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- 
INF\lib 


4 Unzip the nidp. jar file in your working directory. 


5 In your working directory, locate the . properties files in the following directories. 


N 


10 


com/novell/nidp/resource/strings 
com/novell/nidp/resource/logging 
com/novell/nidp/resource/jsp 
com/novell/nidp/resource/jcc 
com/novell/nidp/resource/noxlate 
com/novell/nidp/liberty/wsf/idsis/ppservice/model 
com/novell/nidp/liberty/wsf/idsis/epservice/model 
com/novell/nidp/liberty/wsf/idsis/opservice/model 
com/novell/nidp/liberty/wsf/idsis/apservice/model 
com/novell/nidp/liberty/wsf/interaction 
com/novell/nidp/liberty/wsf/idsis/ssservice/model 
com/novell/nidp/servlets/handler/identityeditor 
com/novell/nidp/servlets/handler/identityaccesseditor 
com/novell/nidp/liberty/wsf/idsis/model 
com/novell/nidp/liberty/wsf/idsis/authority/ldap/attribute/plugins/resources 
com/novell/nidp/liberty/wsf/idsis/ldapservice/model 


The properties files that have been localized contain the messages that end users might see. 
The properties files that have not been localized contain messages that the end users must not 
see. 


Locate the messages you want to customize and copy them to your custom file. 


All the messages you want to customize are placed in this file, even though they come from 
different properties files. Your file must look similar to the following if you selected to customize 
messages from the nidp_resources_en_US.properties file and the 
SSModelResources_en_US.properties file. For example: 


NIDPMAIN.100=An Identity Provider response was received that failed to 
authenticate this session. 

NIDPMAIN.101=A request for identity federation could not be completed. 
NIDPMAIN.102=A request for identity federation termination could not be 
completed. 


SS.WKSLdapCreds = LDAP Credentials 
SS.WKSELdapCredsUserName = LDAP User Name 
SS.WKSELdapCredsUserDN = LDAP User DN 
SS.WKSELdapCredsUserPassword = LDAP Password 
SS.WKSX509Creds = X509 Credentials 


(Conditional) If you are supporting multiple languages, copy the messages to each custom 
language file. 

Replace the messages in the file with your custom messages. 

Replace the string after the equals (=) sign with your translated or customized message. 


If you are using double-byte characters, the characters need to be in Unicode, hexadecimal 
format with a \u prefix. For example: \u5c71. 


Save the file. 
Copy the custom properties file to the following directory on all Identity Servers in the cluster: 
Linux: /opt/novell/nam/idp/webapps/nidp/WEB-INF/classes 
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Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- 
INF\classes 


11 (Optional) To enable messages about the loading of the custom properties files, enable debug 
logging: 
11a Click Devices > Identity Servers > Edit > Auditing and Logging. 
11b In the Component File Logger Levels section, select Debug level for Application. 
11c Click OK, then update Identity Server. 
12 Restart Tomcat. 
¢ Linux Identity Server: Enter one of the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
+ Windows Identity Server: Enter the following commands: 
net stop Tomcat7 
net start Tomcat7 
13 (Optional) To verify the loading of the custom properties files: 
13a View the log file by clicking Auditing > General Logging. 
13b Search for messages similar to the following in the catalina.out or stdout. log file: 


The named Custom Properties File was loaded and will be used: 


Custom Properties File successfully loaded! Name: <Custom Properties 
FileName> 


An error occurred loading a specific Custom Properties File. Loading of 
other Custom Properties Files will continue. 


<Error Description>, Attempting to load Custom Properties File! Name: 
<Custom Properties FileName> 


The locale specifier in the Custom Properties File filename could not be 
successfully parsed into a valid locale. Loading of other Custom Properties 
Files will continue. 


Custom Properties File load failed. Could not determine correct locale! 
Name: <Custom Properties FileName> 


A general error occurred loading Custom Properties Files. Loading will stop 
and all un-loaded Custom Properties Files will not be loaded. 


<Error Description>, Attempting to load Custom Properties Files! 


To create custom error pages for Access Gateway, see Section 4.2.9.2, “Customizing Error 
Messages and Error Pages on Access Gateway,” on page 325. 


Customizing the Branding of the Error Page 


The error page (err_legacy.jsp) is returned when Identity Server encounters an error with the 
following message: 


Error: Unable to authenticate, (300101014-esp-01E79F6000B87D4E8 ) 


The file is located in the following directory. 
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Linux: /opt/novell/nids/1lib/webapp/jsp 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat\webapps\nidp\jsp 
IMPORTANT: After you have customized this page, you need to ensure you back up this page before 


doing an upgrade. The upgrade process overrides any custom changes made to the 
err_legacy.jsp page. 


For information about customizing the error message, see “Customizing Messages” on page 274. 
You can customize the following items: 

+ The window title and the display title. See “Customizing the Titles” on page 277. 

+ The header image and the Novell logo. See “Customizing the Images” on page 277. 

¢ Background colors. See “Customizing the Colors” on page 277. 
Customizing the Titles 


The window title appears in the browser title bar. To replace this text, open the err_legacy. jsp file 
and locate the following text that appears between the <head></head> tags: 


<title><%=handler .getResource(JSPResDesc. TITLE)%></title> 


Replace the content between the <title> and </title> tags with the title you want to appear. For 
example: 


<title>My Company</title> 


The display title is the title that appears in the top frame of the page. Locate the following text that 
appears in the <body> of the page: 


<div id="title"><%=handler .getResource(JSPResDesc .PRODUCT )%></div> 


Replace the content between the <div id="title"> and </div> with the title you want to appear. 
For example: 


<div id="title">My Company</div> 
Customizing the Images 


To replace the header image, open the err_legacy.jsp file and locate the following text in the body 
of the file. 


<div><img src="/nesp/images/AccessMan_Login_Head.png"></div> 

Replace the value of the src attribute with the path and filename of the image you want to use. 
To replace the Novell logo image, locate the following text in the body of the file. 

<div id="logo"><img src="/nesp/images/AccessMan31_Nlogo.png"></div> 

Replace the value of the src attribute with the path and filename of the image you want to use. 
Customizing the Colors 


To change the background colors on the page, modify the color values in the <style> section of the 
<head>. 
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4.1.3.5 


Customizing Tooltip Text for Authentication Contracts 


The strings that the users see when they mouse over the cards for authentication contracts can be 
customized. If you need to support only one language, modify the text in Administration Console. 
1 Click Devices > Identity Servers > Edit > Local > Contracts. 
2 Click the name of a contract, then click Authentication Card. 
3 Replace the English text in the Text option with the required language, then click OK. 
4 Repeat Step 2 and Step 3 for each contract in the list. 
5 Click OK, then update Identity Server. 
If you need to support multiple languages, you need to localize the tooltips. The nidsCardText 
attribute of the nidsAuthLocalContract object needs to be changed to a resource ID. The following 
procedure explains how to do this in Administration Console. You can also use an LDAP browser. 
1 Click Devices > Identity Servers > Edit > Local > Contracts. 


2 Click the name of a contract, then click Authentication Card. 


wo 


Replace the text in the Text option with a resource ID. 

For example, replace Name/Password - Form with CUSTOM_NamePwdFormToolTip. 
Click OK. 

Repeat Step 2 through Step 4 for each contract in the list. 

Click OK, then update Identity Server. 


N Oo oO f 


Use custom string resource files to define the localized strings: 
7a Change to the WEB-INF/classes directory. 
7b For each supported language, create a properties file. For example: 


nidp_custom_resources_fr.properties 
nidp_custom_resources_es.properties 


If you have already created these files for custom messages (see “Customizing Messages” 
on page 274), use the existing files. 

7c For each resource ID you have created, add an entry that contains the resource ID and the 
text you want displayed for that language. For example: 
CUSTOM_NamePwdFormToolTip=Forma de Nombre/Clave 


7d Repeat Step 7c for each supported language file. 
8 Restart Tomcat. 
¢ Linux Identity Server: Enter one of the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
+ Windows Identity Server: Enter the following commands: 


net stop Tomcat7 net start Tomcat7 


Maintaining Customized Identity Server 


If you have customized JSP files for Identity Server, you must perform few steps to maintain the 
customized files before upgrading Access Manager. If you do not, Access Manager overwrites the 
customized JSP files. For more information, see “Maintaining Customized JSP Files for Identity 
Server” in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 
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4.1.3.6 


Sample Custom Login Pages 


e “Modifying the File” on page 279 

¢ “Sample Modified File” on page 282 

e “Modified login.jsp File for Credential Prompts” on page 285 
+ “Custom nidp.jsp File with Custom Credentials” on page 287 
+ “Custom 3.2.x or Later login.jsp File” on page 294 

e “Custom login.jsp File” on page 297 


NOTE: After customizing a JSP file, you need to sanitize the JSP file to prevent XSS attacks. See, 
Section 10.7, “Preventing Cross-site Scripting Attacks,” on page 930. 


Modifying the File 


The following 4.0 login. jsp file has been modified to display line numbers. The lines that require 
modifications have been highlighted, and a few extra spaces have been added to allow for a better 
display of the text. 


<%@ page language="java" %> 

<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%> 
<%@ page import="com.novell.nidp.common.provider.*" %> 

<%@ page import="java.util.*" %> 

<%@ page import="java.net.*" %> 

<%@ page import="com.novell.nidp.*" %> 

<%@ page import="com.novell.nidp.servlets.*" %> 

<%@ page import="com.novell.nidp.resource.*" %> 

9. <%@ page import="com.novell.nidp.resource.jsp.*" %> 

10.<%@ page import="com.novell.nidp.common.xml.w3c.*" %> 


ONOOARWNE 


11.<% 

12. response.setHeader("Pragma", "No-cache"); 13. response. setHeader ("Cache- 
Control", "no-cache"); 14. 15. Locale locale = request.getLocale(); 16. 

String strLanguageCode = locale.getLanguage(); 17. String strImageDirectory = 
NIDPResourceManager .getInstance().getImage Directory(locale); 18. NIDPResource 
resource = NIDPResourceManager .getInstance().get (JSPResDesc.getInstance(), 
locale); 

19 .%> 

20. 


21.<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//<%=strLanguage 
Code%>"> 
22.<html lang="<%=strLanguageCode%>"> 


23. <head> 

24, <link rel="stylesheet" href="<%= request.getContextPath() %>/images/ 
hf_style.css" type="text/css"> 

25. <style type="text/css" media="screen"><!-- 

26. #headimage { position: relative; top: Opx; left: Opx; z-index: 1} 
27. #title { position: relative; top: 40px; left: 5px; color: white; z- 
index: 4} 

28. #locallabel { position: relative; top: 78px; left: 10px; z-index: 4} 
29. #login { text-align: center } 

30. --></style> 

31. <META HTTP-EQUIV="Content-Language" CONTENT="<%=strLanguageCode%>"> 

32. <title><%=resource.getStringO(JSPResDesc.LOGIN_TITLE)%></title> 

33. <meta http-equiv="content-type" content="text/html;charset=utf-8"> 

34, <script type="text/javascript" src="<%= request.getContextPath() %>/images/ 
showhide_2.js"></script> 

35. <script language="JavaScript"> 
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36. 


37. var i = 0; 

38. function imageSubmit( ) 

39. { 

40. if (i == 0) 

41. { 

42. iSi; 

43. document .IDPLogin.submit(); 

44. } 

45. 

46. return false; 

47. } 

48. </script> 

49. </head> 

50. <body marginwidth="0" marginheight="0" leftmargin="0" topmargin="0" 
rightmargin="0" onLoad="document .IDPLogin.Ecom_User_ID.focus();" > 

51. <form name="IDPLogin" enctype="application/x-www-form-urlencoded" 


method="POST" action="<%= (String) request.getAttribute("url") %>" 
AUTOCOMPLETE="0f f"> 


52. <table style="margin-top: 6em" width="100%" border="0" cellspacing="0" 
cellpadding="0"> 

53. <tr> 

54. <td width="50%" height="80 px">&nbsp;</td> 

55. <td colspan="2"> 

56. <div id="title"><b><%=resource.getStringO(JSPResDesc. 
LOGIN_TITLE)%></b></div> 

57. <div id="locallabel"><b><%=resource.getString0(JSPResDesc. 
LOCAL_LOGIN)%></b></div> 

58. <div id="headimage"><img src="<%= request.getContextPath() %>/images/ 
Odyssey_LoginHead.gif" alt="" height="80" width="550" border="0"></div> 

59. </td> 

60. <td width="100%">&nbsp; </td> 

61. </tr> 

62. <tr> 

63. <td width="50%">&nbsp; </td> 

64. <td style="background-color: #efeee9; padding: 10px" colspan="2"> 
65.<% 

66. String err = (String) request.getAttribute(NIDPConstants.ATTR _LOGIN_ERROR); 
67. if (err != null) 

68. { 

69. %> 

70. <div><label><%=err%></label></div> 

71. <% } 

72. 

73 // Determine if this login page is being used for account identification 74. 
// purposes 75. String id = (String) request.getAttribute("identify"); 76. if 
(id != null && id.equals("true")) 77. { 78. %> 79. 

<div><%=resource. getString0(JSPResDesc.IDENTIFY)%></div> 80. <% } %> 

81. <span id="login2" style="display: block;"> 

82. <table> 

83. <tr> 

84. <td nowrap="nowrap"> 

85. <div> 

86. <label style="width: 100px"><%=resource.getStringO 
(JSPResDesc . USERNAME )%></label></label> 

87. </div> 

88. </td> 

89. <td width="100%" nowrap="nowrap"> 

90. <div> 

91. <input type="text" class="smalltext" name="Ecom_User_ID" 
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size="30"> 


92. </div> 

93. </td> 

94. </tr> 

95. <tr> 

96. <td nowrap="nowrap"> 

97. <div> 

98. <label><%=resource. getStringO(JSPResDesc .PASSWORD)%></label> 
99. </div> 

100. </td> 

101. <td style="white-space: nowrap"> 

102. <div> 

103. <input type="password" class="smalltext" name="Ecom_ 
Password" size="30">&nbsp;&nbsp; 

104. <input alt="<%=resource.getString0(JSPResDesc.LOGIN)%>" 


border="0" name="loginButton2" src="<%= request.getContextPath() %>/images/ 
<%=strImageDirectory%>/btnlogin_<%=strImageDirectory%>.gif" type="image" 
value="Login" onClick="return imageSubmit()"> 


105. </div> 

106. </td> 

107. </tr> 

108.<% 109. String prov = (String) request.getAttribute("provision"); 110. if 
(prov != null) 111. { 112.%> 113. <tr> 114. <td 
colspan=2> 115. <div> 116. <label><a 
href="<%=prov%>"><%=resource.getStringO (JSPResDesc.CREATE_ACCT)%></a></label> 
117. </div> 118. </td> 119. 

</tr> 120.<% } %> 

121. </table> 

122. </span> 

123. </td> 

124. <td width="100%">&nbsp;</td> 

125. </tr> 

126. <% 127. DisplayableProvider[] list = (DisplayableProvider[]) request.get 
Attribute("providers"); 128. if (list != null && list.length > 0) 129. { 
130.%> 131. <tr> 132. <td width="50%"></td> 133. <td 
style="background-color: #efeeec; padding-left: 10px; padding-bottom: 
10px"colspan="2"> 134. <div style="margin-left: -10px; background: url(<%= 


request .getContextPath() %>/images/dotline_bg.gif) repeat-x">&nbsp;</div> 135. 
<div><b><%=resource. getString0(JSPResDesc .FEDERATED_LOGIN)%></b></div> 136 .<% 137. 


for (int i = 0; i < list.length; i++) 138. { 139.%> 140. <a 
style="padding: 5px" href="<%=list[i].getAuthenticationUrl 

(request .getContextPath())%>"> 141.<% 142. if (list[i].hasIcon()) 143. 
{ 144.%> 145. <img border=0 class="margin4" 


alt="<%=XMLUtil.stringToHTML String(list[i] .getDisplayName())%>" 
src="<%=XMLUtil.stringToHTMLString (list[i].getIcon(request ) )%>" 


align="absmiddle"></a> 146 .<% 147. } 148. else 149. { 150.%> 

151. <%=XMLUtil.stringToHTMLString(list[i] .getDisplayName())%></a> 152.<% 
153. } 154. 155. } %> 156. </td> 157. <td width="100%"></ 
td> 158. </tr> 159.<% } %> 

160. <tr> 

161. <td width="50%"></td> 

162. <td style="background-color: #E6D88C; padding-left: 10px"><img 


style="padding-right: 200px" src="<%= request.getContextPath() %>/images/ 
LAP_interoperable_logo_100.gif" align="absmiddle" border="0"></td> 

163. <td style="background-color: #E6D88C; padding-right: 10px" 
align="right" width="100"> 

164. 

165.<% 166. String cancel = (String) request.getAttribute("cancel"); 167. if 
(cancel != null) 168. { 169.%> 170. <input 
alt="<%=resource.getString0(JSPResDesc. CANCEL)%>"_ border="0" name="Cancel" 
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src="<%= request.getContextPath() %>/images/<%=strImageDirectory%>/ 
btncancel_<%=strImageDirectory%>.gif" type="image" value="Cancel" tabindex="4"> 


171.<% } 172. else 173. { 174.%> 175. &nbsp; 176.<% } 
%> 

177. </td> 

178. <td width="100%"></td> 

179. </tr> 

180.<% 

181. if (NIDPCripple.isCripple() ) 

182. { 

183 .%> 

184. <tr> 

185. <td colspan=4 width="100%" align="center"><%=NIDPCripple. 
getCrippleAdvertisement (locale )%></td> 

186. </tr> 

187.<% 

188. } 

189 .%> 

190. </table> 

191. </form> 

192. </body> 


193.</html> 


Sample Modified File 


The following file shows all the changes that allow 4.0 login. jsp to compile on a 4.0 SP1 Identity 
Server. The deleted lines have been replaced with returns, so you can line this file up with the original 
to see the modifications. 


<%@ page language="java" %> 

<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%> 
<%@ page import="com.novell.nidp.common.provider.*" %> 

<%@ page import="java.util.*" %> 

<%@ page import="com.novell.nidp.ui.*" %> 

<%@ page import="com.novell.nidp.*" %> 

<%@ page import="com.novell.nidp.servlets.*" %> 

<%@ page import="com.novell.nidp.resource.*" %> 

<%@ page import="com.novell.nidp.resource.jsp.*" %> 

<%@ page import="com.novell.nidp.common.xml.w3c.*" %> 

<% 

ContentHandler handler = new ContentHandler (request, response); 


%> 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional// 
<%=handler .getLanguageCode( )%>"> 
<html lang="<%=handler .getLanguageCode( )%>"> 
<head> 
<link rel="stylesheet" href="<%= request.getContextPath() %>/images/ 
hf_style.css" type="text/css"> 
<style type="text/css" media="sScreen"><! -- 


#headimage { position: relative; top: Opx; left: Opx; z-index: 1} 
#title { position: relative; top: 40px; left: 5px; color: white; z-index: 
4} 
#locallabel { position: relative; top: 78px; left: 10px; z-index: 4} 
#login { text-align: center } 
--></style> 


<META HTTP-EQUIV="Content-Language" CONTENT="<%=handler .getLanguageCode( )%>"> 
<title><%=handler .getResource( JSPResDesc. TITLE)%></title> 
<meta http-equiv="content-type" content="text/html;charset=utf-8"> 
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<script type="text/javascript" src="<%= request.getContextPath() %>/images/ 
showhide_2.js"></script> 
<script language="JavaScript"> 


var i = 0; 
function imageSubmit( ) 
{ 
if (i == 0) 
{ 
i1=1; 
document .IDPLogin.submit(); 
} 
return false; 
} 
</script> 
</head> 


<body marginwidth="0" marginheight="0" leftmargin="0" topmargin="0" 
rightmargin="0" onLoad="document .IDPLogin.Ecom_User_ID.focus();" > 
<form name="IDPLogin" enctype="application/x-www-form-urlencoded" 
method="POST" action="<%= (String) request.getAttribute("url") %>" 
AUTOCOMPLETE="0off"> 
<table style="margin-top: 6em" width="100%" border="0" cellspacing="0" 
cellpadding="0"> 
<tr> 
<td width="50%" height="80 px">&nbsp;</td> 
<td colspan="2"> 
<div id="title"><b><%=handler .getResource(JSPResDesc.TITLE)%></b></div> 
<div id="locallabel"><b><%=handler .getResource(JSPResDesc .PRODUCT )%></b></ 
div> 
<div id="headimage"><img src="<%= request.getContextPath() %>/images/ 
Odyssey_LoginHead.gif" alt="" height="80" width="550" border="0"></div> 


</td> 
<td width="100%">&nbsp; </td> 
</tr> 
<tr> 


<td width="50%">&nbsp; </td> 
<td style="background-color: #efeee9; padding: 10px" colspan="2"> 
<% 
String err = (String) request.getAttribute(NIDPConstants.ATTR_LOGIN_ERROR); 
if (err != null) 


{ 


<div><label><%=er r%></label></div> 


%> 
<span id="login2" style="display: block;"> 
<table> 
<tr> 
<td nowrap="nowrap"> 
<div> 
<label style="width: 
100px"><%=handler .getResource(JSPResDesc .USERNAME )%></label></label> 
</div> 
</td> 
<td width="100%" nowrap="nowrap"> 
<div> 
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<input type="text" class="smalltext" name="Ecom_User_ID" 
size="30"> 
</div> 
</td> 
</tr> 
<tr> 
<td nowrap="nowrap"> 
<div> 
<label><%=handler .getResource(JSPResDesc .PASSWORD )%></label> 
</div> 
</td> 
<td style="white-space: nowrap"> 
<div> 
<input type="password" class="smalltext" name="Ecom_Password" 
size="30">&nbsp; &nbsp; 
<input alt="<%=handler .getResource(JSPResDesc.LOGIN)%>" 
border="0" name="loginButton2" src="<%=handler.getImage("btnlogin.gif", true)%>" 
type="image" value="Login" onClick="return imageSubmit()"> 
</div> 
</td> 
</tr> 


</table> 
</span> 
</td> 
<td width="100%">&nbsp;</td> 
</tr> 


<tr> 
<td width="50%"></td> 
<td style="background-color: #E6D88C; padding-left: 10px"><img 
style="padding-right: 200px" src="<%= request.getContextPath() %>/images/ 
LAP_interoperable_logo_100.gif" align="absmiddle" border="0"></td> 
<td style="background-color: #E6D88C; padding-right: 10px" align="right" 
width="100"> 


</td> 
<td width="100%"></td> 
</tr> 
<% 
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if (NIDPCripple.isCripple() ) 
{ 
%> 
<tr> 
<td colspan=4 width="100%" 
align="center"><%=NIDPCripple.getCrippleAdvertisement (request .getLocale())%></td> 
</tr> 
<% 
} 
%> 
</table> 
</form> 
</body> 
</html> 


Modified login.jsp File for Credential Prompts 


The following code is a modified version of the 3.2 login. jsp file. It has been modified to add a 
prompt for the user’s email address. 


Such a JSP file must be used with a contract that uses a method that defines the query for the new 
attribute. The method also needs to define which login file has been modified to display the prompt. 
For more information about this process, see “Customizing the Default Login Page to Prompt for 
Different Credentials” on page 257. 


The sample code contains the following the text for the prompt: 


<td align=left> 
<label>Email Address:</label> 
</td> 


It also adds an input element for the query variable: 


<td align=left> 
<input type="text" class="smalltext" name="Ecom_User_Mail" size="30"> 
</td> 


These elements are both part of the new <tr> element that has been added to the file. These lines 
are marked in bold in the following sample file. 


<%@ page language="java" %> 

<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%> 

<%@ page import="java.util.*" %> 

<%@ page import="com.novell.nidp.*" %> 

<%@ page import="com.novell.nidp.servlets.*" %> 

<%@ page import="com.novell.nidp.resource.*" %> 

<%@ page import="com.novell.nidp.resource.jsp.*" %> 

<%@ page import="com.novell.nidp.ui.*" %> 

<% 
ContentHandler handler = new ContentHandler (request, response); 
String target = (String) request.getAttribute("target"); 

%> 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional// 
<%=handler .getLanguageCode( )%>"> 
<html lang="<%=handler .getLanguageCode( )%>"> 
<head> 
<META HTTP-EQUIV="Content-Language" 
CONTENT="<%=handler . getLanguageCode( )%>"> 
<meta http-equiv="content-type" content="text/html;charset=utf-8"> 
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<style type="text/css" media="screen"> 


td label { font-size: 0.85em ; padding-right: 0.2em; } 


label { font-size: 0.77em; padding-right: 0.2em; } 
input { font-family: sans-serif; } 


.instructions { color: #4d6d8b; font-size: 0.8em; margin: 


</style> 


<script type="text/javascript" src="<%= 
handler .getImage("showhide_2.js", false)%>"></script> 
<script language="JavaScript"> 


var i= 0; 
function imageSubmit( ) 
{ 
if (i == 0) 
{ 
Los 
document .IDPLogin.submit(); 
} 
return false; 
} 
</script> 
</head> 


© 10px 10px 0 } 


<body style="background-color: <%=handler .getBGColor()%>" marginwidth="0" 


marginheight="0" leftmargin="0" topmargin="0" rightmargin="0" 
onLoad="document . IDPLogin.Ecom_User_ID.focus();" > 


<form name="IDPLogin" enctype="application/x-www-form-urlencoded" 


method="POST" action="<%= (String) request.getAttribute("url") %>" 


AUTOCOMPLETE="0f f"> 

<input type="hidden" name="option" value="credential"> 
<% if (target != null) { %> 

<input type="hidden" name="target" value="<%=target%>"> 
<% } %> 


<table border=0 style="margin-top: 1em" width="100%" cellspacing="0" 


cellpadding="0"> 
<tr> 
<td style="padding: Opx"> 
<table border=0> 
<tr> 
<td align=left> 


<label><%=handler .getResource(JSPResDesc .USERNAME )%></label> 


</td> 
<td align=left> 


<input type="text" class="sSmalltext" name="Ecom_User_ID" 


size="30"> 

</td> 

</tr> 

<tr> 
<td align=left> 

<label>Email Address:</label> 

</td> 
<td align=left> 


<input type="text" class="sSmalltext" name="Ecom_User_Mail" 


size="30"> 
</td> 
</tr> 
<tr> 
<td align=left> 


<label><%=handler .getResource(JSPResDesc .PASSWORD )%></label> 


</td> 
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<td align=left> 
<input type="password" class="smalltext" name="Ecom_Password" 
size="30"> 
</td> 
</tr> 
<tr> 
<td align=right colspan=2 style="white-space: nowrap"> 
<input alt="<%=handler.getResource(JSPResDesc.LOGIN)%>" border="0" 
name="loginButton2" src="<%= handler .getImage("btnlogin. gif", true)%>" type="image" 
value="Login" onClick="return imageSubmit()"> 
</td> 
</tr> 
</table> 
</td> 
</tr> 
<% 
String err = (String) request.getAttribute(NIDPConstants.ATTR_LOGIN_ERROR); 
if (err != null) 


%> 
<td style="padding: 10px"> 
<div class="instructions"><%=err%></div> 
</td> 
</tr> 
<% } %> 


if (NIDPCripple.isCripple() ) 


%> 
<tr> 
<td width="100%" 
align="center"><%=NIDPCripple.getCrippleAdvertisement (request .getLocale())%></td> 


</tr> 
<% 
} 

%> 

</table> 

</form> 

</body> 

</html> 


Custom nidp.jsp File with Custom Credentials 


To create a custom nidp_legacy. jsp file that uses custom credentials, you need to modify the 
nidp_legacy. jsp file, create a method and contract for the file, and modify the main. jsp file. For 
instructions, see “Customizing the nidp.jsp File” on page 260 and “Adding Logic to the main.jsp File 
on page 267 


Figure 4-3 illustrates the login page that the following custom nidp_legacy.jsp file and main. jsp 
file create. 
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Figure 4-3 Custom Branding with Custom Credential Prompts 
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Username: | 


Email Address: 


Password: 
Login 


The credential frame uses the same modifications in the sample from “Modified login.jsp File for 
Credential Prompts” on page 285. The following sections provide the other required sample files to 
create this login page and information about the required method and contract: 


+ “The Modified nidp.jsp File” on page 288 

+ “The Modified main.jsp File” on page 293 

+ “The Method and the Contract” on page 294 
The Modified nidp.jsp File 


The background, menu, and border colors are set to black. These colors are specified in the following 
lines in the sample file: 


// Background color 
String bgcolor = "#000000"; 


// Menu color 
String menucolor = "#000000"; 


// Border color 
String bcolor = "#000000"; 


Figure 4-4 illustrates the image (images2. jpeg) that this custom page uses for the header 
background image: 


Figure 4-4 Background Image 


O 


8 


This image is the repeatable image that allows the header to be resized. This image is specified in the 
following lines in the file: 
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// The header background image that gets repeated 
String hdrBgndImg = "/custom_images/images2. jpeg"; 


Figure 4-5 illustrates the image (images3. jpeg) that this custom page uses for the product logo that 
appears on left of the header frame. 


Figure 4-5 Header Image 


Figure 4-6 illustrates the image (hhbimages. jpeg) that this custom page uses to replace the Novell 
company logo on the right of the header frame. 


Figure 4-6 Company Logo 


The following lines define what appears as the title for the browser window: 
<title>HHB WORLD</title> 

The following line defines the header title value: 

String hdrTitle = "Enter MY WORLD"; 

Its position is controlled by the following line in the file: 


#title { position: absolute; font-size: 1.2em; color: white; top: 18px; left: 
85px; } 


The top position has been modified from 13px to 18px and the left position has been modified from 
55px to 85px. The other lines in this section control the position of the other items in the header. 


The lines that have been modified are marked in bold in the following file. 


<% 
ContentHandler handler = new ContentHandler (request, response); 


// Background color 


String bgcolor = "#000000"; 

// Menu color 

String menucolor = "#000000"; 

// Border color 

String bcolor = "#000000"; 

// The header background image that gets repeated 
String hdrBgndImg = "/custom_images/images2.jpeg"; 
String hdrImage = "/custom_images/images3.jpeg"; 
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String hdrLogo = "/custom_images/hhbimages. jpeg"; 
String hdrTitle = "Enter MY WORLD"; 


String query request.getQueryString(); 
if (query != Prine && query.length() > 0) 
query = "&" + query; 
else query = ""; 
%> 


<!DOCTYPE HTML PUBLIC "-//W3C//Dtd HTML 4.0 transitional// 
<%=handler .getLanguageCode( )%>"> 
<html lang="<%=handler .getLanguageCode( )%>"> 
<head> 
<title>HHB WORLD</title> 
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> 
<link href="<%= handler .getImage("hf_menu.css", false)%>"_ rel="stylesheet"> 
<link href="<%= handler.getImage("HF_message.css", false)%>" 
rel="stylesheet"> 
<link href="<%= handler.getImage("HF_obj_list_table.css", false)%>" 
rel="stylesheet"> 


<style> 
* { margin: 0; padding: 0; } 
#header { background-image: url(<%= 
handler .getImage(hdrBgndImg, false)%>); background-repeat: repeat-x; } 
#logo { position: absolute; top: Opx; right: Opx; } 
#title { position: absolute; font-size: 1.2em; color: white; top: 
18px; left: 85px; } 
#subtitle { position: relative; font-size: .9em; color: black; white-space: 
nowrap; top: Opx; left: Opx; text-align: right; } 
#mcontent { position: relative; padding: 5px; background-color: 
<%=bgcolor%>; } 
#content { width: 100%; border: 0; margin: 0; padding: 0; overflow: none; 


height: 376px; background-color: <%=bgcolor%>; } 
#logoutbut { position: absolute; top: 25px; right: 35px; } 
#helpbutlogin { position: absolute; color: yellow; top: 25px; right: 10px; } 
#loggingbut { position: absolute; color: blue; top: 25px; right: 65px; } 


.NLtab .tabis { background-color: <%=menucolor%>; padding-left: 3px; 
padding-right: 8px; text-align: center; white-space: nowrap; } 

.NLtab .tabis a { text-decoration: none; } 

.NLtab span.tabis { padding:5; color: white; font-size: 0.9em; font-weight: 
bold; line-height: 17px; background-color: transparent; background-image: none; 
text-decoration: none; } 

.NLtab .tab1u { background-color: <%=bgcolor%>; padding-left: 3px; padding- 
right: 3px; text-align: center; white-space: nowrap; border-left: 1px solid 
<%=bcolor%>; border-right: 1px solid <%=bcolor%>; border-top: 1px solid 
<%=bcolor%>; } 

.NLtab span.tabiu { border: none; padding:5; color: black; font-size: 0.8em; 
font-weight: bold; line-height: 17px; text-decoration: none; background-color: 
transparent; } 


.NLtab tr.subtab td { color: white; padding: 2px } 
.NLtab tr.subtab a { font-size: .8em; color: white; text-decoration: none; 
padding: 2px 5px 2px 5px} 


.selx { border: 1px solid rgb(239, 238, 236); font-size: 1em; font-weight: 
bolder; background-repeat: repeat-x; background-position: Opt bottom; } 

.unselx { border: Opx; font-size: .9em; font-weight: normal; background-image: 
none; } 
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var g_cardContainer = null; 


</style> 


<script> 


var g_curCard = null; // initial displayed card 


var g_curSubtab = null; // subtab currently displayed 
var g_curTab = null; 


var menuItem = 0; 
function showHide(i) 


{ 


document. 
document. 
document. 
document. 
document. 
document. 


if (i == 1) 


// tab currently displayed 


getElementById('menu1').style.display='none'; 
getElementById('menu2').style.display='none'; 
getElementById('submenu1').style.display='none'; 
getElementById('submenu2').style.display='none'; 
getElementById('menu' + i).style.display='block'; 
getElementById('submenu' + i).style.display='block'; 


switchContentPage("<%= handler.getJSP("content")%>"); 


else 


switchContentPage("<%= handler.getJSP("IdentityEditor")%>") ; 


} 


function switchContentPage(newSrc) 


{ 
} 


parent.document.getElementById("content").src = newSrc; 


function onloadhandler () 


{ 


} 


g_cardContainer 
g_curSubtab 
g_curTab 
g_curCard 


document .getElementById("cardcontainer"); 
document .getElementById("loginsubtab") ; 
document .getElementById("authtab"); 
document .getElementById("selectedCardo"); 


function showhideTab(divid) 


{ 


} 


var elementi = document.getElementById(divid) ; 


if(elementi.style.display == "none") 


{ 


elementi.style.display = "block"; 
g_curTab.style.display = "none"; 


g_curTab = elementi; 


function subtabchange(divid) 


{ 


var elementi = document.getElementById(divid) ; 
var element2 = g_curSubtab; 

elementi.className = "selx"; 

if (elementi.id != element2.id) 


{ 


element2.className = "unselx"; 


g_curSubtab = element1; 
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function showHelp() 


var helpURL = "login.html"; 
if (g_curSubtab.id == "fedsubtab") 
helpURL = "<%=handler.getHelp("federations.htm1")%>"; 


else if (g_curSubtab.id == "myprofile") 
helpURL = "<%=handler.getHelp("myprofile.htm1")%>"; 


else if (g_curSubtab.id == "Sharing") 
helpURL = "<%=handler.getHelp("sharing. html" )%>"; 


else if (g_curSubtab.id == "loginsubtab") 
helpURL = "<%=handler.getHelp("userlogin.htm1")%>"; 


else if (g_curSubtab.id == "newcardsubtab") 
helpURL = "<%=handler.getHelp("newcard.htm1")%>"; 


else if (g_curSubtab.id == "logTicketsubtab" ) 
helpURL = "<%=handler.getHelp("logticket.htm1")%>"; 


var w; 
w = window.open(helpURL, "nidsPopupHelp", 
"toolbar=no, location=no, directories=no, menubar=no, scrollbars=yes, resizable=yes, wid 
th=500, height=500"); 
if (w != null) 


{ 
w.focus(); 
} 
} 
</script> 
</head> 


<body onload="onloadhandler ()"> 
<table width=100% border=0 cellpadding=0 cellspacing=0 bgcolor=<%=bgcolor%> 


> 
<tr> 
<td> 
<table cellspacing=0 width=100% border=0> 
<tr> 
<td width=100%> 
<div id="header"><img src="<%=handler .getImage(hdriImage, false)%>"></ 
div> 
<div id="logo"><img src="<%=handler .getImage(hdrLogo, false)%>"></ 
div> 
<div id="title"><%=hdrTitle%></div> 
</td> 
</tr> 
</table> 
</td> 
</tr> 
<tr> 
<td> 
<table cellspacing=5 width=100%> 
<tr> 
<td> 
<%@ include file="menus.jsp" %> 
</td> 
</tr> 
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</table> 
</td> 
</tr> 
<tr> 
<td> 
<table cellspacing=0 border=0 width=100%> 
<tr> 
<td> 
<iframe scrolling=no id="content" 
src="<%=handler .addCardParm(handler.getJSP(handler.isJSPMsg() ? 
handler .getJSPMessage().getJSP() : NIDPConstants.JSP_CONTENT)) + query%>" 
frameborder=0></iframe> 
</td> 
</tr> 
</table> 
</td> 
</tr> 
</table> 
</body> 
</html> 


The Modified main.jsp File 


The following sample file has two types of modifications. The following line has been added so that 


the URI of the contract can be read and used as a condition for selecting the login page to display: 


String strContractURI = hand.getContractURI(); 


The following lines define the login page to use when the URI of the contract is set to login/custom. 


else if(strContractURI != null && strContractURI.equals("login/custom")) 
{ 


%> 
<%@ include file="custom.jsp" %> 
<% } 
The lines that have been added are marked in bold in the following file. 


<%@ page language="java" %> 

<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%> 
<%@ page import="com.novell.nidp.*" %> 

<%@ page import="com.novell.nidp.resource.jsp.*" %> 

<%@ page import="com.novell.nidp.ui.*" %> 

<%@ page import="com.novell.nidp.common.util.*" %> 

<%@ page import="com.novell.nidp.liberty.wsf.idsis.apservice.schema.*" %> 


<% 
ContentHandler hand = new ContentHandler(request, response); 
String strContractURI = hand.getContractURI(); 


// Is there a JSP defined on a class definition or a method definition 
// that must be displayed as the main jsp here? 

if (hand.contractDefinesMainJSP() ) 

{ 


%> 


<%@ include file="mainRedirect.jsp" %> 
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else if(strContractURI != null && strContractURI.equals("login/custom" ) ) 
{ 


%> 
<%@ include file="custom.jsp" %> 
<% } 


// This is the jsp used by default 
else 


{ 
%> 
<%@ include file="nidp.jsp" %> 
<% } %> 
The Method and the Contract 


After modifying the two files, you still need to create a method and a contract. The method needs to 
use a name/password class and have the following properties defined: 


+ Query property values: 
Property Name: Query 


Property Value: (&(objectclass=person) (mail=%Ecom_User_Mail%) ) 
+ JSP property values: 

Property Name: JSP 

Property Value: </ilename> 


Replace <filename> with the name of your login page that modifies the credential prompts. Do 
not include the JSP extension in the value. 


You then need to create a contract that uses this method and assign it to a protected resource. 


Custom 3.2.x or Later login.jsp File 


To create this type of page, you need to start with the login. jsp file that ships with Access Manager 
3.2.x or later and then add the required code for a header. Figure 4-7 illustrates such a page. 


Figure 4-7 Custom Page Derived from the login.jsp File 
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To create this page, see the following sections: 


+ “The Modified login.jsp File” on page 295 
+ “The Method and the Contract” on page 297 


The Modified login.jsp File 


This custom page does not modify the credential frame. The lines that define the window title (HHB 
CUSTOM LOGIN), the page header title (ITS ANEW WORLD), and the image (hhbimages.png) are 
marked in bold in the following sample file. 


<%@ page language="java" %> 
<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%> 
<%@ page import="java.util.*" %> 
<%@ page import="com.novell.nidp.*" %> 
<%@ page import="com.novell.nidp.servlets.*" %> 
<%@ page import="com.novell.nidp.resource.*" %> 
<%@ page import="com.novell.nidp.resource.jsp.*" %> 
<%@ page import="com.novell.nidp.ui.*" %> 
<% 
ContentHandler handler = new ContentHandler (request, response); 
String target = (String)request.getAttribute("target"); 
String hdrImage = "/custom_images/hhbimages. jpeg"; 


%> 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional// 
<%=handler .getLanguageCode( )%>"> 
<html lang="<%=handler .getLanguageCode( )%>"> 
<head> 
<title>HHB CUSTOM LOGIN </title> 
<META HTTP-EQUIV="Content-Language" CONTENT="<%=handler .getLanguageCode( )%>"> 
<meta http-equiv="content-type" content="text/html;charset=utf-8"> 


<style type="text/css" media="screen"> 


td label { font-size: 0.85em ; padding-right: 0.2em; } 
label { font-size: 0.77em; padding-right: 0.2em; } 
input { font-family: sans-serif; } 
.instructions { color: #4d6d8b; font-size: 0.8em; margin: © 10px 10px © } 
</style> 


<script type="text/javascript" src="<%= 
handler .getImage("showhide_2.js", false)%>"></script> 
<script language="JavaScript"> 
var i = 0; 
function imageSubmit( ) 
if (i == 0) 
{ . 
i = 1; 
document .IDPLogin.submit(); 
} 


return false; 


</script> 
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</head> 
<body text="lightcyan" style="background-color:Black" marginwidth="300" 
marginheight="100" leftmargin="350" topmargin="0" rightmargin="0" 
onLoad="document . IDPLogin.Ecom_User_ID.focus();" > 
<br> 
<hi><u> IT'S A NEW WORLD</u></h1i> 


<form name="IDPLogin" enctype="application/x-www-form-urlencoded" 

method="POST" action="<%= (String) request.getAttribute("url") %>" 
AUTOCOMPLETE="0ff"> 

<input type="hidden" name="option" value="credential"> 
<% if (target != null) { %> 

<input type="hidden" name="target" value="<%=target%>"> 
<% } %> 

<table border=0 style="margin-top: 1em" width="20" cellspacing="0" 
cellpadding="0"> 
<tr> 
<div id="headimage"><img 
src="<%=handler.getImage(hdrImage, false)%>" alt="" height="80" width="150" 
border="0"></div> 
</tr> 
<tr> 


<td style="padding: Opx"> 
<table border=0> 
<br><br> 


<tr> 
<td align=center> 
<label><%=handler . getResource( JSPResDesc .USERNAME )%></ 
label> 
</td> 
<td align=center> 
<input type="text" class="smalltext" name="Ecom_User_ID" 
size="30"> 
</td> 
</tr> 
<tr> 
<td align=center> 
<label><%=handler . getResource( JSPResDesc .PASSWORD )%></ 
label> 
</td> 
<td align=center> 
<input type="password" class="smalltext" 
name="Ecom_Password" size="30"> 
</td> 
</tr> 
<tr> 
<td align=right colspan=2 style="white-space: nowrap"> 
<input alt="<%=handler.getResource(JSPResDesc.LOGIN)%>" 
border="0" name="loginButton2" src="<%= handler.getImage("btnlogin.gif", true)%>" 
type="image" value="Login" onClick="return imageSubmit()"> 
</td> 
</tr> 
</table> 
</td> 
</tr> 
<% 
String err = (String) request.getAttribute(NIDPConstants.ATTR_LOGIN_ERROR); 
if (err != null) 
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%> 
<td style="padding: 10px"> 
<div class="instructions"><%=err%></div> 
</td> 
</tr> 
<% } %> 
<% 
if (NIDPCripple.isCripple() ) 
{ 
%> 
<tr> 
<td width="100%" 
align="center"><%=NIDPCripple.getCrippleAdvertisement (request .getLocale())%></td> 


</tr> 
<% 
} 
%> 
</table> 
</form> 
</body> 
</html> 


The Method and the Contract 


After modifying the file, you still need to create a method and a contract. The method needs to use a 
name/password class and have the following properties defined: 


¢ JSP property values: 
Property Name: JSP 
Property Value: </ilename> 


Replace <filename> with the name of your custom login page. Do not include the JSP extension 
in the value. 
¢ MainJSP property values: 
Property Name: MainJSP 
Property Value: true 


You then need to create a contract that uses this method and assign it to a protected resource. 


Custom login.jsp File 


To create this type of page, you need to start with the login. jsp file that shipped with Access 
Manager 3.2.x or later. For instructions, see “Modifying the File” on page 279. 


The following diagram illustrates a page that has been modified to remove the Novell branding and 
logo. It has also been modified to prompt the user for an e-mail address in addition to a username 
and password. 
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To create this page, see the following sections: 


+ “Modifying the File” on page 298 
+ “The Method and the Contract” on page 301 


Modifying the File 


The bold lines in the following sample file are the lines that have been modified to change the 
branding and the login prompts. 


<%@ page language="java" %> 
<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%> 
<%@ page import="com.novell.nidp.common.provider.*" %> 
<%@ page import="java.util.*" %> 
<%@ page import="com.novell.nidp.ui.*" %> 
<%@ page import="com.novell.nidp.*" %> 
<%@ page import="com.novell.nidp.servlets.*" %> 
<%@ page import="com.novell.nidp.resource.*" %> 
<%@ page import="com.novell.nidp.resource.jsp.*" %> 
<%@ page import="com.novell.nidp.common.xml.w3c.*" %> 
<% 
ContentHandler handler = new ContentHandler(request, response); 
%> 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional// 
<%=handler .getLanguageCode( )%>"> 
<html lang="<%=handler .getLanguageCode( )%>"> 
<head> 
<link rel="stylesheet" href="<%= request.getContextPath() %>/images/ 
hf_style.css" type="text/css"> 
<style type="text/css" media="Screen"><! -- 
#headimage { position: relative; top: Opx; left: Opx; z-index: 1} 
#title { position: relative; top: 40px; left: 5px; color: white; z-index: 


4} 


298 = Setting Up an Advanced Access Manager Configuration 


#locallabel { position: relative; top: 78px; left: 10px; z-index: 4} 
#login { text-align: center } 
--></style> 
<META HTTP-EQUIV="Content-Language" CONTENT="<%=handler .getLanguageCode( )%>"> 
<title>MY WORLD</title> 
<meta http-equiv="content-type" content="text/html;charset=utf-8"> 
<script type="text/javascript" src="<%= request.getContextPath() %>/images/ 
showhide_2.js"></script> 
<script language="JavaScript"> 


var i = 0; 
function imageSubmit( ) 
{ 
if (i == 0) 
{ 
t= i; 
document .IDPLogin.submit(); 
} 
return false; 
} 
</script> 
</head> 


<body marginwidth="0" marginheight="0" leftmargin="0" topmargin="0" 
rightmargin="0" onLoad="document .IDPLogin.Ecom_User_ID.focus();" > 
<form name="IDPLogin" enctype="application/x-www-form-urlencoded" 
method="POST" action="<%= (String) request.getAttribute("url") %>" 
AUTOCOMPLETE="0off"> 
<table style="margin-top: 6em" width="100%" border="0" cellspacing="0" 
cellpadding="0"> 
<tr> 
<td width="50%" height="80 px">&nbsp;</td> 
<td colspan="2"> 
<div id="title"><b>HHB Partner</b></div> 
<div id="locallabel"><b>My Company</b></div> 
<div id="headimage"><img src="<%= request.getContextPath() %>/images/ 
Odyssey_Head.gif" alt="" height="80" width="550" border="0"></div> 


</td> 
<td width="100%">&nbsp; </td> 
</tr> 
<tr> 


<td width="50%">&nbsp; </td> 
<td style="background-color: #efeee9; padding: 10px" colspan="2"> 
<% 
String err = (String) request.getAttribute(NIDPConstants.ATTR_LOGIN_ERROR); 
if (err != null) 
{ 
%> 
<div><label><%=err%></label></div> 
<% } 


// Determine if this login page is being used for account identification 
// purposes 
%> 
<span id="login2" style="display: block;"> 
<table> 
<tr> 
<td nowrap="nowrap"> 
<div> 
<label style="width: 
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100px"><%=handler .getResource(JSPResDesc .USERNAME )%></label></label> 
</div> 
</td> 
<td width="100%" nowrap="nowrap"> 
<div> 
<input type="text" class="smalltext" name="Ecom_User_ID" 
size="30"> 
</div> 
</td> 
</tr> 
<tr> 
<td nowrap="nowrap"> 
<div> 
<label style="width: 100px">Email Address:</label></label> 
</div> 
</td> 
<td width="100%" nowrap="nowrap"> 
<div> 
<input type="text" class="smalltext" name="Ecom_User_Mail" 
size="30"> 
</div> 
</td> 
</tr> 


<tr> 
<td nowrap="nowrap"> 
<div> 
<label><%=handler .getResource(JSPResDesc .PASSWORD )%></label> 
</div> 
</td> 
<td style="white-space: nowrap"> 
<div> 
<input type="password" class="smalltext" name="Ecom_Password" 
size="30">&nbsp; &nbsp; 
<input alt="<%=handler .getResource(JSPResDesc.LOGIN)%>" 
border="0" name="loginButton2" src="<%=handler.getImage("btnlogin.gif", true)%>" 
type="image" value="Login" onClick="return imageSubmit()"> 
</div> 
</td> 
</tr> 
</table> 
</span> 
</td> 
<td width="100%">&nbsp; </td> 
</tr> 


<tr> 
<td width="50%"></td> 
<td style="background-color: #E6D88C; padding-left: 10px"><img 
style="padding-right: 200px" src="<%= request.getContextPath() %>/images/ 
LAP_interoperable_logo_100.gif" align="absmiddle" border="0"></td> 
<td style="background-color: #E6D88C; padding-right: 10px" align="right" 
width="100"> 


</td> 
<td width="100%"></td> 
</tr> 
<% 
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if (NIDPCripple.isCripple() ) 
{ 


%> 
<tr> 
<td colspan=4 width="100%" 
align="center"><%=NIDPCripple.getCrippleAdvertisement (request .getLocale())%></td> 
</tr> 
<% 
} 
%> 
</table> 
</form> 
</body> 
</html> 


The Method and the Contract 


After modifying the file, you still need to create a method and a contract. The method needs to use a 
name/password class and have the following properties defined: 


+ Query property values: 
Property Name: Query 


Property Value: (&(objectclass=person) (mail=%Ecom_User_Mail%) ) 
+ JSP property values: 

Property Name: JSP 

Property Value: </ilename> 


Replace <filename> with the name of your custom login page. Do not include the JSP extension 
in the value. 


¢ MainJSP property values: 
Property Name: MainJSP 
Property Value: true 


You then need to create a contract that uses this method and assign it to a protected resource. 


Access Gateway Server Advance Configuration 


This section describes the configuration settings that affect Access Gateway as a server, such as 
changing its name or setting the time. 

¢ Section 4.2.1, “Configuration Overview,” on page 302 

¢ Section 4.2.2, “Saving, Applying, or Canceling Configuration Changes,” on page 303 

¢ Section 4.2.3, “Managing Access Gateways,” on page 304 

¢ Section 4.2.4, “Managing General Details of Access Gateway,” on page 312 

¢ Section 4.2.5, “Setting Up a Tunnel,” on page 317 

¢ Section 4.2.6, “Setting the Date and Time,” on page 318 

¢ Section 4.2.7, “Configuring Network Settings,” on page 319 


¢ Section 4.2.8, “Enabling Access Gateway to Display Post-Authentication Message,” on 
page 324 


¢ Section 4.2.9, “Customizing Access Gateway,” on page 325 
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For logging and audit options, see the following: 


¢ Section 21.4.1, “Managing Access Gateway Logs,” on page 1048 

¢ Section 21.4.4, “Configuring Logging for a Proxy Service,” on page 1050 
¢ Section 19.3, “Enabling Access Gateway Audit Events,” on page 1024 

¢ Section 4.4, “Access Gateway Advanced Options,” on page 338 


4.2.1 Configuration Overview 


The Configuration page allows you to view the configuration status and to configure the features of 
the cluster or Access Gateway. After an Access Gateway has been made a member of a cluster, you 
can only configure it from the cluster configuration. Some options are specific to an Access Gateway. 
For these options, you must select Access Gateway and then configure the options. 


1 In Administration Console Dashboard, Devices > Access Gateways > Edit. 


To edit an Access Gateway that is not a member of a cluster, click the Edit button on Access 
Gateway row. 


To edit an Access Gateway cluster, click the Edit button on Access Gateway cluster row. 
2 Select one of the following options: 


Reverse Proxy / Authentication: Allows you to configure a reverse proxy so that it hides the IP 
address of a Web server and accelerates access by caching the most frequently used pages. 
This option displays the list of configured proxies and allows you to add new proxies and modify 
existing proxies. To add a new reverse proxy or manage the existing proxies, click Reverse 
Proxy / Authentication (see Section 3.8.2, “Managing Reverse Proxies and Authentication,” on 
page 119). To manage a specific reverse proxy, click its name (see “Creating a Proxy Service” on 
page 121). 


Tunneling: Allows you to tunnel non-HTTP traffic through Access Gateway to a Web server. For 
more information, see Section 4.2.5, “Setting Up a Tunnel,” on page 317. 


Date & Time: Allows you to configure the server’s time source. For more information, see 
Section 4.2.6, “Setting the Date and Time,” on page 318. 


Alerts: Allows you to select the alerts and then configure whether they are sent to a server, a log 
file, or to selected individuals via e-mail. For more information, see Section 25.2.3, “Managing 
Access Gateway Alert Profiles,” on page 1110. 


Auditing: Allows you to select the events to send to a Sentinel or Audit server. For more 
information, see Section 19.3, “Enabling Access Gateway Audit Events,” on page 1024. 


Adapter List: Displays the list of configured network cards and allows you to edit an existing 
configuration or to add a new one. For more information, see “Viewing and Modifying Adapter 
Settings” on page 319. To manage a specific adapter, click the name of the adapter. 


Gateways: Displays the list of configured gateways and allows you to edit an existing 
configuration or to add a new one. For more information, see “Viewing and Modifying Gateway 
Settings” on page 321. 


DNS: Displays the current DNS configuration that Access Gateway is using to resolve names 
and allows you to modify it. For more information, see “Viewing and Modifying DNS Settings” on 
page 322. 


Hosts: Allows you to create a static mapping between the host IP addresses and host names. 
For more information, see “Configuring Hosts” on page 323. 


Service Provider Certificates: Displays information about the certificates assigned to the 
Embedded Service Provider component of Access Gateway. For more information, see 
“Managing Embedded Service Provider Certificates” on page 968. 
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Purge List: Allows you to prevent Web objects from being cached. For more information, see 
Section 4.3.4, “Configuring a Purge List,” on page 336. 


Pin List: Allows you to prepopulate the cache with the Web objects that you want cached, 
before a user has requested the object. For more information, see Section 4.3.3, “Configuring a 
Pin List,” on page 333. 


Cache Options: Allows you to globally disable caching or configure which objects are cached 
and how frequently they are refreshed. For more information, see Configuring Caching Options. 


Advanced Options: Allows you to configure how all reverse proxies handle specific items in 
cache. For more information, see Section 4.4.1, “Configuring Global Advanced Options,” on 
page 338. 


3 For information about using the OK, Cancel, and Revert buttons, see Section 4.2.2, “Saving, 
Applying, or Canceling Configuration Changes,” on page 303. 


Saving, Applying, or Canceling Configuration Changes 


When you make configuration changes on a page accessed from Devices > Access Gateways > Edit 
and click OK on that page, the changes are saved to the browser cache. If your session expires or 
you close the browser session before you update Access Gateway with the changes, the changes 
are lost. 


The Configuration page allows you to control how your changes are saved so they can be applied 
with the update options (see “Configuration Options” on page 307). 


If you have any configuration changes saved to the browser cache, use the following options to 
control what happens to the changes: 


OK: To save the configuration changes to the configuration store, click OK. This allows you to return 
at a later time to review or modify the changes before they are applied. If your Access Gateways are 
clustered and you prefer to update them one at a time, you need to save the configuration change. 
This ensures that the changes aren't lost before the last cluster member is updated. When your 
session times out or you log out, the configuration changes are flushed from the browser cache. If this 
happens before the changes have been applied to some servers in the cluster, the changes cannot 
be applied to those servers. 


If you decide to cancel the saved changes, click the Revert button and the saved configuration is 
overwritten by the last successfully applied configuration. 


Cancel: To cancel changes that are pending in the browser cache, click the Cancel button. To cancel 
modifications to specific services, click the Cancel link by the service. The Cancel button does not 
affect the changes that have been saved to the configuration store. 


Revert: To cancel any saved changes, click Revert, then confirm the cancellation. The saved 
configuration is overwritten by the last successfully applied configuration. 


If you have applied the changes to one member of the cluster, you cannot use the Revert button to 
revert to the configuration you had before applying the changes. If you decide you do not want to 
apply these changes to other members of the cluster, remove the server that you updated with the 
changes from the cluster. Then click Revert to cancel the saved changes. The members of the cluster 
return to the last successfully applied configuration. To apply this configuration to the removed server, 
add this server to the cluster. 
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The Revert button and the Cancel button cannot cancel the following configuration changes: 


+ 


Identity Server Cluster: If you change the Identity Server Cluster option on the Reverse Proxy/ 
Authentication page, then click OK, the Revert button cannot cancel this change. It is saved, and 
the next time you apply a configuration change, Identity Server cluster configuration is applied. 
To cancel the change, you need to return to the Reverse Proxy/Authentication page, set the 
Identity Server Cluster option to the original selection, then click OK on the Configuration page. 


Reverse Proxy for the Embedded Service Provider: If you change the Reverse Proxy option 
on the Reverse Proxy/Authentication page, then click OK, the Revert button cannot cancel this 
change. It is saved, and the next time you apply a configuration change, the Reverse Proxy 
option change is applied. To cancel the change, return to the Reverse Proxy/Authentication 
page, set the Reverse Proxy option to the original selection, then click OK on the Configuration 
page. 

Port of the Reverse Proxy for the Embedded Service Provider: If you change the port of the 
reverse proxy that is used by the Embedded Service Provider (click Edit > [Name of Reverse 
Proxy]), then click OK, the Revert button cannot cancel this change. It is saved, and the next 
time you apply a configuration change, the port change is applied. To cancel the change, return 
to the Reverse Proxy page, set the port to the original value, then click OK on the Configuration 
page. 

Published DNS Name of the Proxy Service for the Embedded Service Provider: If you 
change the Published DNS Name of the proxy service that is used by the Embedded Service 
Provider (click Edit > [Name of Reverse Proxy] > [Name of Proxy Service]), then click OK, the 
Revert button cannot cancel this change. It is saved, and the next time you apply a configuration 
change, the Published DNS Name is changed. To undo the change, return to the Proxy Service 
page, set the Published DNS Name to its original value, then click OK on the Configuration page. 


Certificates: Certificates are pushed as soon as they are selected. If you change the server 
certificate for the reverse proxy (click Edit > [Name of Reverse Proxy]) or change the Web server 
certificates (click Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Web Servers), 
the Revert button cannot cancel these changes. To undo the change, return to the page, select 
the original certificate, then click OK. 


Renaming a Reverse Proxy: If you change the name of a reverse proxy (click Edit > Reverse 
Proxies / Authentication), then click OK, you cannot cancel this change. To undo the change, 
return to the Reverse Proxies / Authentication page, rename the reverse proxy to its original 
name, then click OK and update Access Gateway. 
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+ 


+ 


+ 


+ 


The following sections contain information about settings available with Access Gateways, changing 
the settings, and their impact on users: 


Section 4.2.3.1, “Viewing and Modifying Gateway Settings,” on page 305 
Section 4.2.3.2, “Configuration Options,” on page 307 

Section 4.2.3.3, “Impact of Configuration Changes,” on page 309 
Section 4.2.3.4, “Scheduling a Command,” on page 311 
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Viewing and Modifying Gateway Settings 


Use the Servers page to view the status of Access Gateways, to modify their configuration, and to 
perform other actions such as creating a new cluster or stopping and starting an Access Gateway or 
its Embedded Service Provider. 


1 Click Devices > Access Gateways. 
2 Select one of the following: 


New Cluster: To create a new cluster of Access Gateways, click New Cluster. A cluster can be 
one or more Access Gateways. 


For configuration information, see “Creating a New Cluster” on page 114. 


Stop: To stop an Access Gateway Appliance, select the appliance, then click Stop. You must 
have physical access to Access Gateway Appliance machine to start it again. To stop an Access 
Gateway Service, select the service, then click Stop. You can use the Restart option to start 
Access Gateway Service. 


Restart: To reboot an Access Gateway Appliance, select the appliance, then click Restart. 
Access Gateway Appliance is stopped, the operating system is rebooted, then the appliance is 
started. To stop and start an Access Gateway Service, select it, then click Restart. If Access 
Gateway Service is already stopped, use Restart to start it. 


Refresh: To update the list of Access Gateways and the status columns (Status, Health, Alerts, 
Commands), click Refresh. 


3 To perform an action available in the Actions drop-down menu, select an Access Gateway, then 
select one of the following: 


Assign to Cluster: To add the selected Access Gateway to a cluster, select Assign to Cluster, 
then select the cluster. This Access Gateway is reconfigured with the configuration of the primary 
cluster server. An Access Gateway Appliance can only be added to a cluster of Access Gateway 
Appliances. An Access Gateway Service can only be added to a cluster of Access Gateway 
Services. 


Remove from Cluster: To remove the selected Access Gateway from a cluster, select Remove 
from Cluster. Access Gateway retains its configuration from the cluster, but no traffic is sent to it 
until it is reconfigured. You can assign it to a different cluster and have it updated with this 

cluster’s configuration, or you can delete all of its reverse proxies and start a new configuration. 


Delete: To remove the selected Access Gateway server from the list of servers that can be 
managed from this Administration Console, select Delete. If Access Gateway is a member of a 
cluster, you must first remove it from the cluster before you can delete it. 


IMPORTANT: When an Access Gateway is deleted from Administration Console, you can no 
longer manage it. To access it again, you must manually trigger an auto-import, which causes it 
to import into an Administration Console. 


Schedule Restart: To schedule when the selected Access Gateway must be stopped and then 
started, select Schedule Restart. On an Access Gateway Appliance, a restart stops the 
operating system, then starts the operating system and Access Gateway. On an Access 
Gateway Service, a restart stops Access Gateway Service, then starts it. For information about 
how to schedule this command, see “Scheduling a Command” on page 311. 
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Schedule Stop: To schedule when the selected Access Gateway or cluster must be stopped, 
select Schedule Stop. 


+ When you stop an Access Gateway Appliance, you shut down Access Gateway Appliance 
and the operating system. You must have physical access to the machine to start it again. 


+ When you stop an Access Gateway Service, you stop just Access Gateway Service. You 
can use the Restart option to start it again. 


For more information about how to schedule this command, see “Scheduling a Command” on 
page 311 


Purge List Now: Click Purge List Now to cause all objects in the current purge list to be purged 
from the cache of the selected server or cluster. 


Purge All Cache: Click Purge All Cache to purge the server cache for the selected server or 
cluster. All cached content is lost. 


When you make certain configuration changes such as updating or changing certificates, 
changing the IP addresses of Web servers, or modifying the rewriter configuration, you are 
prompted to purge the cache. The cached objects must be updated for users to see the effects of 
such configuration changes. If your Access Gateways are in a cluster, you need to manage the 
purge process so your site remains accessible to your users. You must apply the configuration 
changes to one member of a cluster. When its status returns to healthy and current, issue the 
command to purge its cache. Then apply the changes to the next cluster member. 


IMPORTANT: Do not issue a purge cache command when an Access Gateway has a pending 
configuration change. Wait until the configuration change is complete. 


Update Health from Server: Click this action to send a request to the server for updated health 
information. If you have selected multiple servers, a request is sent to each one. The health 
status changes to an animated circle until the reply returns. 


Service Provider: Select one of the following actions: 


¢ Start Service Provider: To start the Embedded Service Provider associated with the 
selected Access Gateway, click Start Service Provider. The Embedded Service Provider is 
the module within Access Gateway that communicates with Identity Server. 


The service provider must be restarted whenever you enable or modify logging on Identity 
Server. 


¢ Stop Service Provider: To stop the Embedded Service Provider associated with the 
selected Access Gateway, click Stop Service Provider. The Embedded Service Provider is 
the module within Access Gateway that communicates with Identity Server. 


When an Access Gateway is not functioning correctly, you must always try stopping and 
starting the service provider before stopping and starting Access Gateway. 


+ Restart Service Provider: To restart the Embedded Service Provider associated with the 
selected Access Gateway, click Restart Service Provider. This command stops the 
Embedded Service Provider and then starts it. The Embedded Service Provider is the 
module within Access Gateway that communicates with Identity Server. 


When an Access Gateway is not functioning correctly, you must always try restarting the 
service provider before stopping and starting Access Gateway. 


4 Use the following links to manage a cluster or an Access Gateway. 


Name: Displays a list of Access Gateway servers and the clusters that can be managed from 
this Administration Console. 


+ To view or modify the general details of a particular server, click the name of the server. 
¢ To view or modify general details of a cluster, click the name of the cluster. 


306 Setting Up an Advanced Access Manager Configuration 


Status: Indicates the configuration status of the clusters and Access Gateways. Possible states 
are pending, update, current, and update all. For more information, see “Configuration Options” 
on page 307. 


Health: Indicates whether a cluster or an Access Gateway is functional. Click the icon to view 
additional information about the operational status of an Access Gateway. 


¢ For information about the health of a specific Access Gateway, click the health icon on 
Access Gateway row. For more information, see Section 24.4.1, “Monitoring the Health of 
an Access Gateway,” on page 1102. 


¢ For information about the health of a Access Gateway cluster, click the health icon on the 
cluster row. For more information, see Section 24.4.2, “Monitoring the Health of an Access 
Gateway Cluster,” on page 1107. 


Alerts: Indicates whether any alerts have been sent. If the alert count is non-zero, click the count 
to view more information. 


+ For information about the alerts of a specific Access Gateway, click the link on Access 
Gateway row. For more information, see Section 25.2.1, “Viewing Access Gateway Alerts,” 
on page 1110. 


+ For information about the alerts sent to the cluster, click the link on the cluster row. For more 
information, see Section 25.2.2, “Viewing Access Gateway Cluster Alerts,” on page 1110. 


Commands: Indicates the status of the last executed command and whether any commands 
are pending. Click the link to view more information. For more information, see Section 23.2, 
“Viewing the Command Status of Access Gateway,” on page 1094. 


Statistics: Provides a link to the statistic pages. 


¢ For information about the statistics of a specific Access Gateway, click the View link on 
Access Gateway row and see Section 22.2.1, “Monitoring Access Gateway Statistics,” on 
page 1074. 


+ For information about statistics sent to the cluster, click the View link on the cluster row and 
see Section 22.2.2, “Monitoring Access Gateway Cluster Statistics,” on page 1083. 


Edit: Provides a link to the configuration page. If the server belongs to a cluster, the Edit link 
appears on the cluster row. Otherwise, the link is on the server row. See Section 4.2.1, 
“Configuration Overview,” on page 302. 


4.2.3.2 Configuration Options 


Use the information in this section to modify the Status options described in Step 4 on page 306. 


1 Click Devices > Access Gateways. 


2 View the Status column and make changes as necessary. 


Status Description 


Current Indicates that all configuration changes have been applied. 
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Status Description 


Update Indicates that a configuration change has been made, but not applied. To apply 
the changes, click the Update link, then select one of the following:. 


+ 


All Configuration: The All Configuration option causes Access 
Gateway to read its complete configuration file and restarts the 
Embedded Service Provider. 


The configuration update causes logged-in users to lose their 
connections unless the server is a member of a cluster. When the server 
is a member of a cluster, the users are sent to another Access Gateway 
and they experience no interruption of service. 


Logging Settings: When the ESP logging settings have been modified 
on Identity Server, the update option for Logging Settings is available. 
The Logging Settings option causes no interruption in services. When 
you modify Access Gateway logging settings, this option is not available 
because they are considered configuration settings. 


Policy Settings: If a policy is modified for a protected resource of Access 
Gateway and the policy change is the only modification that has 
occurred, the update option for Policy Settings is available. This option 
causes no interruption in services. 


Rewriter Profile Changes: When the administrator changes the rewriter 
profile, a purge cache command is issued to a Gateway from 
Administration Console, the connection is lost and the service is 
interrupted for a few seconds. Similar experience is observed during the 
rewriter profile configuration change, as this internally triggers the purge 
cache command. 


Changing Certificates: When a certificate configuration is changed 
from Administration Console, the service is interrupted due to the Tomcat 
restart. 
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Update All This link is available when a server belongs to a cluster. You can select to 
update all the servers at the same time, or you can select to update them one 
at a time. If the modification is a policy or a logging change, then use Update 
All. If the modification is a configuration change, we recommend that you 
update the servers one at a time. 


+ When you select Update All for a configuration change, users experience 
an interruption of service. 


+ When you update servers one at a time for a configuration change, users 
experience no interruption of service. 


When you make the following configuration changes, the Update All option is 
the only option available and your site will be unavailable while the update 
occurs: 


¢ Identity Server configuration that is used for authentication is changed 
(Access Gateways > Edit > Reverse Proxy/Authentication, then 
select a different value for the Identity Server Cluster option). 


+ Adifferent reverse proxy is selected to be used for authentication 
(Access Gateways > Edit > Reverse Proxy/Authentication, then 
select a different value for the Reverse Proxy option). 


+ The protocol or port of the authenticating reverse proxy is modified 
(Access Gateways > Edit > Reverse Proxy/Authentication > [Name 
of Reverse Proxy], then change the SSL options or the port options). 


+ The published DNS name of the authentication proxy service is modified 
(Access Gateways > Edit > Reverse Proxy/Authentication > [Name 
of Reverse Proxy] > [Name of First Proxy Service], then modify the 
Published DNS Name option). 


For more information, see “Applying Changes to Access Gateway Cluster 
Members” on page 116. 


Update [! | If the configuration update contains a configuration error, the Update link is 
disabled and the Configuration Error icon is displayed. Click the icon to 
discover which objects have been misconfigured. You need to fix the error by 
either canceling or modifying the changes before you can perform an update. 


Update All |! | If the configuration update contains a configuration error, the Update All and 
the member Update links are disabled and the Configuration Error icon is 
displayed. Click the icon to discover which objects have been misconfigured. 
You need to fix the error by either canceling or modifying the changes before 
you can perform an update. 


Pending Indicates that the server is processing a configuration change, but has not 
completed the process. 


Locked Indicates that another administrator is making configuration changes. Before 
you proceed with any configuration changes, you need to coordinate with this 
administrator and wait until Access Gateway has been updated with the other 
administrator's changes. 


4.2.3.3 Impact of Configuration Changes 


This section covers the impact of some of the common Access Gateway configuration settings on 
users. 
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NOTE: Do not push the configuration from Administration Console to devices during peak system 
usage times. 


Devices > Access Gateways 


+ 


Purge List Now/ Purge Cache: Causes a process level restart and terminates all the existing 
connections and downloads. The users do not need to reauthenticate, but issuing a purge list or 
cache command might result in a higher load on the service provider. If there is a single gateway, 
issuing a purge list or cache command can cause temporary service disruption for users. 


Stop: Stops the proxy component in Access Gateway Appliance, makes it unavailable for user 
requests and terminates all the existing connections and downloads. The users do not need to 
reauthenticate, but stopping the proxy component can result in a higher load on the identity 
provider and other gateway cluster members. 


Restart: Triggers a restart of the operating system of Access Gateway Appliance, where all 
existing connections and downloads are terminated. The users do not need to reauthenticate, 
but restarting the operating system can result in a higher load on the identity provider and other 
gateway cluster members. 


Service Provider > Restart: Causes the ESP and proxy to clear the user session information 
and refresh the policy information. Access might be denied to protected resources and 
resources that need policy evaluation during the restart process. 


Service Provider > Stop: Causes the ESP and proxy to clear the user session information. You 
cannot access the protected resources and resources that need policy evaluation. 


Devices > Access Gateways > < your gateway/cluster> Services 


+ 


Rewriter Profile Change: Changing the rewriter profile causes Administration Console to issue 
a purge cache command to Access Gateway. Issuing a purge cache command causes a 
process level restart and terminates all the existing connections and downloads. 


Accelerated Web Service Change: Changing the accelerated Web server details causes 
Administration Console to issue a purge cache command to Access Gateway. Issuing a purge 
cache command causes a process level restart and terminates all the existing connections and 
downloads 


Service Creation: If your gateway cluster is behind an L4 switch, ensure that you review or 
modify the L4 configuration to reflect any new service that you can create. 


TCP Connect Options: Increasing the Data Read Timeout values or the Idle Timeout values 
impacts the user experience if the Web servers are unreachable. Disabling the persistent 
connections also impacts the user experience. 


System Settings 


+ 


Date and Time: Changing date and time or the NTP server configuration impacts the existing 
user session timeout values. It is critical to keep the time settings in Access Gateways and 
Identity Servers synchronized in order to prevent authentication failures and unexpected session 
times out. There is no other impact than authentication failures and unexpected session times 
out. 


Monitoring 


¢ Audit Configuration Changes or Audit Server Health: If the audit server is busy or 


unreachable, it causes a delay in browsing, including Administration Console access. There is 
no other impact than delay in browsing and accessing Administration Console. 
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Network Settings 


+ Network Related Changes: Be cautious in making changes to the network parameters like 
Adapter, IP address, Netmask, Gateways, DNS, Hosts, and Route. The users can be impacted 
by these changes because the connections are reset; however, user reauthentication might not 
be required. Incorrect configuration leads to system inaccessibility on the network and you 
cannot access Access Gateway Service. 


Security Settings 
You must not change security setting options during the peak system usage hours. 
¢ Signing: Before changing it, ensure that Identity Server trust store contains the root CA 
certificate and possible intermediate CA certificates to complete the trust chain. 


¢ Trust Store: Before changing it, ensure that you have all the root CA certificates and possible 
intermediate CA certificates to complete the trust chain to trust any certificates used by Identity 
Server. 


Content Settings 


+ Cache Options: Be cautious in making changes to the cache options. Changing cache options 
can impact the performance of your Access Manager system. You might see an increase or 
decline in Access Gateway performance, depending on the changes made to the cache options. 


Scheduling a Command 


Use the Schedule New Command page to schedule a command, such as a shutdown, restart, or 
upgrade. 
1 Click Devices > Access Gateways. 


2 (Conditional) To schedule a shutdown or restart, select a server, then click Actions > Schedule 
Restart or Schedule Stop. Continue with Step 4. 


3 (Conditional) To schedule an upgrade for Access Gateway Appliance, click [Name of Server] > 
Upgrade > Schedule Upgrade. 


4 Fill in the following fields: 


Name Scheduled Command: (Required) Specify a name for this scheduled command. This 
name is used in log files. 


Description: (Optional) Specify a reason for the command. 
Date & Time: Select the day, month, year, hour, and minute when the command must execute. 
The following fields display information about the command you are scheduling: 


Type: Displays the type of command that is being scheduled, such as Access Gateway 
Shutdown, Access Gateway Restart, or Access Gateway Upgrade. 


Server: Displays the name of the server that the command is being scheduled for. 
5 Click OK to schedule the command. 
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4.2.4 Managing General Details of Access Gateway 


4.2.4.1 


The Server Details page allows you to perform general maintenance actions on the selected Access 
Gateway. 


1 Click Devices > Access Gateways > [Name of Access Gateway]. 


2 Select one of the following options: 


Edit: Click this option to edit the general details of Access Gateway. See “Changing the Name of 
an Access Gateway and Modifying Other Server Details” on page 312. 


New NIC: (Only for 3.1 SP4 Access Gateway Appliance) Click this action to trigger a scan to 
detect a new network interface card that you have added to the machine after installing Access 
Gateway Appliance. This might take some time. For more information, see “Adding New Network 
Interfaces to Access Gateway Appliance” on page 324. 


New IP: Click this action to trigger a scan to detect new IP addresses. This might take some 
time. If you have used a system utility to add an IP address after you have installed Access 
Gateway Service, use this option to update Access Gateway Service to display the new IP 
address as a configuration option. For more information about this option, see “Adding a New IP 
Address to Access Gateway” on page 324. 


Configuration: Click this option to export the configuration of this Access Gateway or to import 
the configuration of a saved configuration file. See “Exporting and Importing an Access Gateway 
Configuration” on page 313. 


3 Click Close. 


Changing the Name of an Access Gateway and Modifying Other 
Server Details 


The default name of an Access Gateway is its IP address. You can change this to a more descriptive 
name as well as modifying other details that can help you identify one Access Gateway from another. 


1 Click Devices > Access Gateways > [Name of Access Gateway] > Edit. 


2 Modify the values in the following fields: 


Name: Specify Administration Console display name for Access Gateway. This is a required 
field. The default name is the IP address of Access Gateway. If you modify the name, the name 
must use alphanumeric characters and can include spaces, hyphens, and underscores. 


Management IP Address: Specify the IP address used to manage Access Gateway. Select an 
IP address from the list. For information about changing the Management IP Address, 
Section 2.4.3, “Changing the IP Address of an Access Gateway Appliance,” on page 53. 


Port: Specify the port to use for communication with Administration Console. 


Location: Specify the location of Access Gateway server. This is optional, but useful if your 
network has multiple Access Gateway servers. 


Description: Describe the purpose of this Access Gateway. This is optional, but useful if your 
network has multiple Access Gateways. 


Click OK twice, then click Close. 
When you click OK, any changes are immediately applied to Access Gateway. 
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4.2.4.2 


Exporting and Importing an Access Gateway Configuration 


You can export an existing Access Gateway configuration and its dependent policies, and then import 
this configuration to a new server. This feature is especially useful for deployments that set up 
configurations in a staging environment, test and validate the configuration, then want to deploy the 
configuration on new hardware that exists in the production environment. 


IMPORTANT: The export feature is not a backup tool. The export feature is designed to handle 
configuration information applicable to all members of a cluster, and network IP addresses and DNS 
names are filtered out during the import. (The server-specific information that is filtered out is the 
information you set specifically for each member in a cluster.) If you want a copy of all configuration 
information, including server-specific information, you need to perform a backup. See Chapter 28, 
“Back Up and Restore,” on page 1129. 


The export feature is not an upgrade tool. You cannot export a configuration from one version of 
Access Manager and import it into a newer version of Access Manager. 


If your Access Gateway is not a member of a cluster and you have configured it to use multiple IP 
addresses, be aware that the export feature filters out multiple IP addresses and uses only ethO. You 
need to use the backup utility to save this type of information. If you need to reinstall the machine, 
leave Access Gateway configuration in Administration Console and reinstall Access Gateway. If you 
use the same IP address for Access Gateway, it imports into Administration Console and inherits the 
configuration. 


When exporting the file, you can select to password-protect the file, which encrypts the file. If you are 
using the exported file to move an Access Gateway from a staging area to a production area and you 
need to change the names of the proxy services and DNS names from a staging name toa 
production area and you need to change the names of the proxy services and DNS names from a 
staging name to a production name, do not select to encrypt the file. You need a simple text file so 
you can search and replace these names. If you select not to encrypt the file, remember that the file 
contains sensitive information and protect it accordingly. 


The following sections explain this process: 


¢ “Exporting the Configuration” on page 313 
+ “Importing the Configuration” on page 315 


e “Cleaning Up and Verifying the Configuration” on page 315 


Exporting the Configuration 


1 Click Devices > Access Gateway > [Name of Access Gateway]. 

2 Click Configuration > Export. 

3 (Conditional) If you want to encrypt the file, fill in the following fields: 
Password protect: Select this option to encrypt the file. 


Password: Specify a password to use for encrypting the file. When you import the configuration 
onto another device, you are prompted for this password. 


4 Click OK, then select to save the configuration to a file. 
The filename is the name of Access Gateway with an xml extension. 


5 (Conditional) If you want to change the names of the proxy services and their DNS names from a 
staging name to a production name, complete the following: 


5a Open the configuration file in a text editor. 
5b Search and remove the staging suffix. 
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If you have specified DNS names with a staging suffix (for example, 
innerwebstaging.provo.novell.com), you can search for staging. provo.novell.com 
and remove staging from the name. 


In particular, you need to change the following: 


+ Any fully qualified DNS names from the staging name to the production name 
(DNSName elements in the file) 


+ The cookie domains associated with each proxy service (AuthenticationCookieDomain 
elements in the file) 


+ The URL masks in pin lists that contain fully qualified names (URLMask elements in 
the file) 


Depending upon your naming standards, you might want to change the names of the 
following: 


+ UserlnterfacelD elements (proxy service, pin list, and protected resource user interface 
ID's) 

+ Description elements (proxy service, pin list, and protected resource descriptions) 

+ Name (proxy service, pin list, and protected resource names) 

¢ SubServicelD elements 

+ MultiHomeMasterSubservicelDRef elements 

+ LogDirectoryName elements 

+ ProfilelDRef elements 

+ ProtectedResourcelD elements 

¢ ProfilelD elements (TCP Listen options name) 


5c (Conditional) If your Web servers in the staging area have different IP addresses and 
hostnames than the Web Servers in the production area, you can search and replace them 
in the configuration file or wait until after the import and modify them in Administration 
Console. 


6 Export the policies used by Access Gateway. Click Policies > Policies, then either select Name 
to include all policies or individually select the policies to export. 


You need to export all Access Gateway policies and any Role policies used by Access Gateway 
policies. 


7 Click Export and modify the proposed filename if needed. 
8 Click OK, then select to save the policy configurations to a file. 


9 (Conditional) If you have created multiple policy containers, select the next policy container in 
the list, and repeat Step 6 through Step 8. 


The policies for each container must be saved to a separate export file. 


10 (Conditional) If your policies redirect users to staging URLs when they are denied access, 
search and replace these URLs with the production URLs. Open the policy file with a text editor 
and search for your staging name. 


11 Copy Access Gateway and policy configuration files to a place accessible by the new Access 
Gateway. 


12 Continue with “Importing the Configuration” on page 315. 
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Importing the Configuration 


1 


13 


Verify that Access Gateway meets the conditions for an import: 


+ Access Gateway must not be a member of a cluster. If it is a member of a cluster, remove it 
from the cluster before continuing. 


Click Devices > Access Gateways, select Access Gateway, then click Actions > Remove 
from Cluster. 


You can create a cluster and add this machine to the cluster as the primary server after you 
have completed the import. 


+ Access Gateway must be an unconfigured machine. If it contains reverse proxies, delete 
them before continuing. 


Click Devices > Access Gateways > Edit > Reverse Proxies / Authentication. In the 
Reverse Proxy List, select Name, then click Delete. Update Access Gateway and Identity 
Server. 


Click Policies > Policies. 
The policies that Access Gateway is dependent upon must be imported first. 


(Conditional) If you have exported policies from more than one container, create the policy 
containers. Click the Containers tab; in the Container List, click New, specify the name for the 
container, then click OK. 


(Conditional) If your system already contains policies, delete them if they are not being used. 


If they are in use and you have policies with the same names as the policies you are going to 
import, you need to manually reconcile the duplicate policies. See step 5 in “Cleaning Up and 
Verifying the Configuration” on page 315. 


In the Policy List, click Import. 

Browse to the location of the policy configuration file, select the file, then click OK. 
(Conditional) If you exported multiple policy configuration files, repeat Step 5 and Step 6. 
Enable all new Role policies. Click Identity Servers > Edit > Roles. 

Either select Name to enable all policies or individually select the policies, then click Enable. 
Click OK, then click Update. 


To import Access Gateway configuration, click Access Gateways > [Name of Access Gateway] 
> Configuration > Import. 


Browse to the location of the configuration file, select the file, enter a password if you specified 
one on export, then click OK. 


Continue with “Cleaning Up and Verifying the Configuration” on page 315. 


Cleaning Up and Verifying the Configuration 


1 


When the configuration import has finished, verify the configuration for your reverse proxies. 
1a Click Access Gateways > Edit > [Name of Reverse Proxy]. 
1b Verify the listening address. 


This is especially important if your Access Gateway has multiple network adapters. By 
default, the IP address of eth0 is always selected as the listening address. 


1c Verify the certificates assigned to the reverse proxy. 


The Subject Name of the certificate must match the published DNS name of the primary 
proxy service in the Proxy Service List. 
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1d Verify the Web Server configuration. In the Proxy Service List, click the Web Server 
Addresses link. Check the following values: 


+ Web Server Host Name: If this name has a staging prefix or suffix, remove it. 


+ IP addresses in the Web Server List: If the IP addresses in the production area are 
different from the IP addresses in the staging area, modify the IP addresses to match 
the production area. 


¢ Certificates: If you have configured SSL or mutual SSL between the proxy service and 
the Web servers, configure the Web Server Trusted Root and SSL Mutual Certificate 
options. The export and import configuration option does not export and import 
certificates. 


le Click OK twice. 
(Conditional) If you have multiple reverse proxies, repeat Step 1 for each proxy service. 


N 


3 On the Configuration page, click Reverse Proxy / Authentication, then select the Identity Server 
Cluster configuration. 


4 Ifyou have multiple reverse proxies, verify that the Reverse Proxy value in the Embedded 
Service Provider section is the reverse proxy you want to use for authentication, then click OK 
twice. 


5 (Conditional) If Administration Console already contained some policies, verify that you do not 
have policies with duplicate names. Click Policies > Policies. 


Policies with duplicate names have Copy-n appended to the end of the name, with n 
representing a number. If you have duplicates, reconcile them: 


+ If they contain the same rules, you need to reconfigure the resources that use one policy to 
use the other policy before you can delete the duplicate policy. 


+ If they contain different rules, rename the duplicate policies. 
6 (Conditional) Apply any policy configuration changes. 
7 Click Access Gateways > Update. 
8 Click Identity Servers > Update. 


If your Identity Server does not prompt you for an update, complete the following steps to trigger 
the update: 


8a Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication. 
8b Set the Identity Server Cluster field to None, then click OK. 
8c Click Reverse Proxy / Authentication. 
8d Set the Identity Server Cluster field to the correct value, then click OK. 
8e Update Access Gateway. 
8f Update Identity Server. 
9 Configure the keystores for Access Gateway. 


If you have configured Access Gateway for SSL between Identity Server and Access Gateway 
and between Access Gateway and the browsers, verify that the trust stores and the keystores 
contain the correct certificates. 


9a Click Security > Certificates. 
9b Find the certificate for Access Gateway. 


The subject name of this certificate must match the DNS name of Access Gateway. If this 
certificate is not in the list, you need to create it or import it. 


This certificate must be in use by the ESP Mutual SSL and Proxy Key Store of Access 
Gateway. 
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4.2.5 


9c If the certificate is not in use by the required keystores, select the certificate, then click 
Actions > Add Certificate to Keystores. 


9d Click the Select Keystore icon, select ESP Mutual SSL and Proxy Key Store of Access 
Gateway, then click OK twice. 


10 Configure the trust stores for Access Gateway. 
10a Click Security > Certificates > Trusted Roots. 


The trusted root certificate of the CA that signed Access Gateway certificate needs to be in 
the NIDP-truststore. 


The trusted root certificate of the CA that signed Identity Server certificate, needs to be in 
the ESP Trust Store of Access Gateway. 


10b If you need to add a trusted root to a trust store, select the trusted root, click Add Trusted 
Roots to Trust Stores. 


10c Click the Trust Store icon, select the required trust store, then click OK twice. 


11 If you made any keystore or trust store modifications, update Access Gateway and Identity 
Server. 


12 (Optional) Create a cluster configuration and add this server as the primary server. 


Setting Up a Tunnel 


The tunnel option lets you create one or more services for the specific purpose of tunneling non- 
HTTP traffic through Access Gateway to a Web server. To do this, the non-HTTP traffic must use a 
different IP address and port combination than the HTTP traffic. 


An Access Gateway usually processes HTTP requests in order to fill them. However, it is not unusual 
that some of the traffic coming through the gateway is not HTTP-based. Web servers sometimes 
handle Telnet, FTP, chat, or other kinds of traffic without attempting to process it. If your Web servers 
are handling this type of traffic, you must set up a tunnel for it. 


Reverse proxies and tunnels cannot share the same IP address and port combination. You can either 
configure a reverse proxy for an IP address and port or a tunnel for that IP address and port. 


To set up a tunnel: 


1 Click Devices > Access Gateways > Edit > Tunneling. 
2 Click New, enter a display name for the tunnel, then click OK. 
3 Specify the following details: 


Enable Tunnel: Specifies that Access Gateway must set up a tunnel for all incoming traffic. This 
option must be enabled to configure a tunnel. 


Tunnel SSL Traffic Only: Allows you to configure Access Gateway to tunnel only SSL traffic. If 
this option is selected, Access Gateway verifies that the address and port being accessed are 
actually an SSL Web site. If verification fails, the service tears down the connection. The SSL 
port number for the SSL tunnel is specified via the Listening Port and the Connect Port. 


Published DNS Name: Specify the DNS name you want the public to use to access your tunnel 
or the virtual IP address assigned to Access Gateway cluster by the L4 switch. If you specify a 
DNS name, the DNS name must resolve to the IP address you set up as the listening address for 
the tunnel. 


4 Configure the communication options between the browsers and the tunnel by configuring the 
following fields: 
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Cluster Member: (Available only if Access Gateway is a member of a cluster.) Select the server 
you want to configure from the list of servers. The Listening Address(es) modifications apply to 
the selected server. Any other modifications apply to all servers in the cluster. 


Listening Address(es): Displays a list of available IP addresses. If Access Gateway has only 
one IP address, only one is displayed. If it has multiple addresses, you can select one or more 
addresses to enable. You must enable at least one address by selecting its check box. 


TCP Listen Options: Provides additional options for configuring how requests are handled. See 
“Configuring TCP Listen Options for Clients” on page 157. At least one Web server must be 
configured before you can modify these options. 


Listening Port: Specifies the port on which to listen for requests from browsers. The listening 
address and port combination must not match any combination you have configured for a 
reverse proxy. 


5 Configure the communication options between the tunnel and the Web servers by configuring 
the following fields: 


Connect Port: Specifies the port that Access Gateway uses to communicate with the Web 
server. 


TCP Connect Options: Allows you to control how idle and unresponsive Web server 
connections are handled and to optimize these processes for your network. See “Configuring 
TCP Connect Options for Web Servers” on page 158. 


6 Specify a Web server to receive the traffic. In the Web Server List section, click New, specify the 
IP address or DNS name of the Web server, then click OK. 


At least one Web server must be specified in the list before you can save a tunnel configuration. 
7 To save your changes to browser cache, click OK. 
8 To apply your changes, click the Access Gateways link, then click Update > OK. 


4.2.6 Setting the Date and Time 


The Date & Time option lets you set the system time for Access Gateway. To set the date and time 
for the Linux or Windows Access Gateway Service, use the utilities supplied by the operating system. 


The time between Identity Server and Access Gateway must be either synchronized or set to be 
within 1 minute of each other for trusted authentication to work. 


To configure the date and time options: 


1 (Access Gateway Appliance) Click Devices > Access Gateways > Edit > Date & Time. 


2 (Conditional) If Access Gateway belongs to a cluster of Access Gateways, select Access 
Gateway from the list displayed in the Cluster Member field. The modifications you make on this 
page apply only to the selected Access Gateway. 


If Access Gateway does not belong to a cluster, this option is not available. 
3 Specify the following details: 


Server Date and Time: Displays the current time and allows you to set the current time. Click 
Set Date & Time Manually, then select the current year, month, day, hour, and minute. 


IMPORTANT: If the date is set to a time before Access Gateway certificates are valid, 
communication to Access Gateway is lost. This error cannot be corrected from Administration 
Console. You need to correct it at the console of Access Gateway machine. 


Use the yast command and select System > Date and Time. 
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Set Up NTP: Click this option to specify the DNS name or IP address of a Network Time 
Protocol server. The installation program enters the name of pool.ntp.org, the DNS name of a 
public NTP server. To disable this feature, you must remove all servers from the NTP Server List. 
This is not recommended. 


Time Zone: Select your time zone, then click OK. Regardless of the method you used to set the 
time, you must select a time zone. 


4 Click OK. 
5 On the Server Configuration page, click OK. 
6 To apply your changes, click Update > OK. 


4.2.7 Configuring Network Settings 


After initial setup, you seldom need to change the network settings unless something in your network 
changes, such as adding a new gateway or DNS server. These options are for Access Gateway 
Appliance. For the Linux or Windows Access Gateway Service, use the utilities supplied by the 
operating system. However, if you add an new network interface card to Access Gateway Service 
machine and use system utilities to configure it and assign it an IP address, you need to update 
Access Gateway Service with this information. See “Adding a New IP Address to Access Gateway” 
on page 324. 


This section describes the following tasks: 


¢ Section 4.2.7.1, “Viewing and Modifying Adapter Settings,” on page 319 

¢ Section 4.2.7.2, “Viewing and Modifying Gateway Settings,” on page 321 

¢ Section 4.2.7.3, “Viewing and Modifying DNS Settings,” on page 322 

è Section 4.2.7.4, “Configuring Hosts,” on page 323 

¢ Section 4.2.7.5, “Adding a New IP Address to Access Gateway,” on page 324 

¢ Section 4.2.7.6, “Adding New Network Interfaces to Access Gateway Appliance,” on page 324 


4.2.7.1 Viewing and Modifying Adapter Settings 


The adapter settings allow you to view the current configuration for the network adapters installed in 
Access Gateway Appliance and manage the IP addresses that are assigned to them. 


¢ If you want to configure an adapter to use more than one IP address, you can use these settings 
to add them. 


¢ If you have multiple adapters installed on an Access Gateway Appliance machine, you can only 
configure ethO during installation. Use the procedure described in this section to configure the 
others. 


+ If you have added an adapter to the machine after installing Access Gateway, you need to use 
the New NIC option before it can appear in the adapter list. 


If you have added an adapter to the machine after installing Access Gateway, you need to use 
the New NIC option before it can appear in the adapter list. 


To view or modify your current adapter settings: 


1 Click Devices > Access Gateways > Edit > Adapter List. 


2 (Conditional) If Access Gateway is a member of a cluster, select the server you want to configure 
from the list of servers in the Cluster Member field. All changes made to this page apply to the 
selected server. 
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3 Select the adapter you want to modify, then select one of the following actions: 


+ To add anew subnet to an existing adapter, click New. 


+ To delete a subnet, select a subnet, then click Delete. More than one subnet must be 
configured for you to delete one. 


+ To modify an existing subnet, click the IP address of the subnet. 


4 To configure a new subnet or a new IP address for a subnet, configure the following fields: 


Subnet: Displays the address of the subnet that you are modifying. This is empty if you are 
creating a new subnet. 


Subnet Mask: (Required) Specifies the subnet mask address for this subnet. The address can 
be specified in standard dotted format or in CIDR format. 


IP Addresses: Allows you to manage the IP addresses assigned to the subnet. 
+ To add an address, click New, specify the address, then click OK. 
+ To delete an address, select the address, then click Delete. 


+ To change the IP address, see Section 2.4.3, “Changing the IP Address of an Access 
Gateway Appliance,” on page 53. 


5 Click OK. 
6 Configure the Adapter List Options. 


These options let you change settings for the network adapters on Access Gateway to ensure 
compatibility with an existing LAN. Modify the default settings only if your LAN requires 
specialized adapter card changes. 


+ Speed: Select Default, 10 MB, 100 MB, or 1000 MB. 
+ Duplex: Select Default, Half, or Full. 


IMPORTANT: Some network adapter drivers do not correctly detect duplex settings. This is 
a general industry problem with Fast Ethernet technology. 


If your Access Gateway isn't performing as expected, check to ensure that the duplex 
settings for its network adapters match your network configuration. It might be necessary to 
manually configure the duplex settings on both your Access Gateway and your Ethernet 
switch or hub. 


+ NAT: Select Dynamic or Disabled. 


If Access Gateway is serving as a router, and your network employs non-unique private IP 
addresses, you can configure Access Gateway to provide Network Address Translation 
(NAT) services. 


For example, if you have a 10.0.0.0 private network on ethO and a registered public network 
such as 130.0.0.0 on eth1, the clients on the private network can access the Internet 
through Access Gateway, provided that the Dynamic option is selected in the NAT drop- 
down list for the eth1 adapter. 


Access Gateway then functions as a network address translator and dynamically maps the 
private, non-routable 10-net addresses to the registered public address assigned to eth1. 


IMPORTANT: You cannot configure a reverse proxy on an IP address assigned to an 
adapter that has the Dynamic option set for NAT. NAT and a reverse proxy cannot coexist 
on the same adapter. 


7 Click OK. 
8 On the Server Configuration page, click OK, then click Update > OK. 
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Viewing and Modifying Gateway Settings 


The gateway settings display the current gateway configuration that Access Gateway Appliance is 
using to route packets. On this page, you can also configure additional gateways. During installation, 
you could specify only a default gateway. You must have at least one gateway defined for Access 
Gateway to function. 


Access Gateway routes requests to specific destinations through these gateways. If a request could 
be routed through multiple gateways, Access Gateway chooses the gateway associated with the 
most restrictive mask (the smallest range of destination addresses). The default gateway is used only 
when no other routes apply. 


Gateways fall within the following three basic groups: 


+ Host gateways for specific destination addresses. 

e Network gateways for destination addresses that fall within specific subnets. 

+ The default gateway for destination addresses that aren’t covered by host or network gateways. 
Access Gateway uses additional gateways only when the Act As Router option is selected. When 
this option is selected, you can add Host Gateways and Network Gateways. When configuring a Host 


Gateway or Network Gateway, you specify the IP address of the host or network gateway in the Next 
Hop field. This address must be on the same subnetwork as the IP address for Access Gateway. 


IMPORTANT: If you enter an IP address that is on a different subnetwork, Access Gateway reports 
this error on the Health page, after the configuration has been applied. 


To modify your current gateway configuration: 


1 (Access Gateway Appliance) Click Devices > Access Gateways > Edit > Gateways. 


2 (Conditional) If Access Gateway is a member of a cluster, select the server you want to configure 
from the list of servers in the Cluster Member field. All changes made to this page apply to the 
selected server. 


3 Fill in the following fields: 


Act as Router: Select this option if Access Gateway functions as the default gateway for clients 
on the network. If you select this option, you can specify additional gateways. 


Enable Gateway Statistics Monitoring: Select this option if you want to gather statistics and 
monitor the traffic on the gateways. 


4 Configure your default gateway, which specifies the gateway to use when no other routes apply. 
Configure the following: 


Next Hop: The IP address of the gateway. 


Metric: A relative number indicating the bias you can add to the normal flow of gateway logic. 
Specifying a number higher than 1 makes this resource more expensive and alters the gateway 
logic used. Valid numbers include 1 through 16. 


Type: Gateways are active if they publish their presence, or passive if they do not. 


5 Configure your host gateways, which are the gateways to be used for packets being sent to 
specific hosts. When you select New from the Host Gateway list, you are asked for the following 
information: 


Next Hop: The address of the host gateway that is to be used. 


Host: The IP address of the destination host. Valid addresses cannot be the first or last address 
of a class and must be unique. 
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Metric: A relative number indicating the bias you can add to the normal flow of gateway logic. 
Specifying a number higher than 1 makes this resource more expensive and alters the gateway 
logic used. Valid numbers include 1 through 16. 


Type: Gateways are active if they publish their presence, or passive if they do not. 
Click OK when the fields are configured. 


6 Configure your network gateways, which are the gateways to be used for packets being sent to 
specific subnets. When you select New from the Network Gateway list, you are asked for the 
following information: 


Next Hop: The address of the gateway that is to be used. 


Network Address: The subnet address for the destination IP address range. You must enter the 
valid subnet address. 


Mask: The subnet mask for the subnet or IP address above. A valid entry must be at least as 
large as a class mask where a Class A mask is 255.0.0.0, a Class B mask is 255.255.0.0, and 
Class C, D, and E masks are 255.255.255.0. 


Metric: A relative number indicating the bias you can add to the normal flow of gateway logic. 
Specifying a number higher than 1 makes this resource more expensive and alters the gateway 
logic used. Valid numbers include 1 through 16. 


Type: Gateways are active if they publish their presence, or passive if they do not. 
Click OK when the fields are configured. 

7 Click OK. 

8 On the Server Configuration page, click OK, then click Update > OK. 


4.2.7.3 Viewing and Modifying DNS Settings 


The DNS page displays the current configuration for domain name services for Access Gateway 
Appliance and allows you to modify it. 


1 (Access Gateway Appliance) Click Devices > Access Gateways > Edit > DNS. 


2 (Conditional) If Access Gateway is a member of a cluster, select the server you want to configure 
from the list of servers in the Cluster Member field. All changes made to this page apply to the 
selected server. 


3 Specify the following details: 


Server Hostname: Displays the unique host or computer name that you have assigned to 
Access Gateway machine. If you modify this name, you need to modify the entry for Access 
Gateway in your DNS server to resolve this new name. 


Domain: Specifies the domain name for your network. Your DNS server must be configured to 
resolve the combination of the server hostname and the domain name to Access Gateway 
machine. This field assumes you are using dotted names for your machines, such as 
sales.mytest.com, where sales is the Server Hostname and mytest.com is the Domain. 


DNS Server IP Addresses: Displays the IP addresses of the servers on your network that 
resolve DNS names to IP addresses. You can have up to three servers in the list. If you specified 
any addresses during installation, they appear in this list. To manage the servers in this list, 
select one of the following options: 


+ New: To add a server to the list, click this option and specify the IP address of a DNS 
server. 


+ Delete: To delete a server from the list, select the address of a server, then click this option. 
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4.2.7.4 


¢ Order: To modify the order in which the DNS servers are listed, select the server, then click 
either the up-arrow or the down-arrow buttons. The first server in the list is the first server 
contacted when a DNS name needs to be resolved. 


4 Configure the DNS Cache Settings. These options allow you to control the refresh of DNS 
information. These are all standard DNS options. 


Negative Lookup: Specifies how long a failed DNS lookup domain name remains in cache. If 
Access Gateway cannot resolve a domain name, it stores that information in its cache for the 
specified amount of time. If Access Gateway receives requests for that domain name within this 
period, it sends a “Bad Gateway” error message to the browser and does not resolve the domain 
name again. Valid field values include 0-3600 seconds. The default is120 seconds. 


Minimum Time To Live per Entry: Specifies the minimum amount of time that DNS entries 
remain in cache before they expire. This is the minimum value Access Gateway uses regardless 
of the value the DNS server returns. Valid field values include 0O—-3600 seconds. The default is 
120 seconds. 


Maximum Time To Live per Entry: Specifies the maximum amount of time that DNS entries 
remain in cache before they expire. This is the maximum value Access Gateway uses regardless 
of the value the DNS server returns. Valid field values include 0-744 hours. The default is 168 
hours. 


Maximum Entries: Specifies the maximum number of DNS cache entries. When this number is 
reached, Access Gateway deletes old entries to make room for newer ones. Valid field values 
include 2000—100000. The default is 5000. 


DNS Transport Protocol: Specifies the transport protocol that DNS uses on the network where 
Access Gateway is installed. Valid values are UDP and TCP. The default is UDP. 


5 Click OK. 
6 On the Server Configuration page, click OK, then click Update > OK. 


Configuring Hosts 


You can configure Access Gateway Appliance to have multiple hostnames or to resolve DNS names 
to IP addresses. If you manually edit the /etc/hosts file, your modifications are lost when Access 
Gateway Appliance is updated. However, if you use the Hosts page to specify the entries, the entries 
are written to the /etc/hosts file whenever the configuration of Access Gateway Appliance is 
updated. 

1 (Access Gateway Appliance) Click Devices > Access Gateways > Edit > Hosts. 


2 (Conditional) If Access Gateway is a member of a cluster, select the server you want to configure 
from the list of servers in the Cluster Member field. All changes made to this page apply to the 
selected server. 


3 To add a new hostname to an existing IP address, click the name of a Host IP Address. 


4 In the Host Name(s) text box, specify a name for the host. Place each hostname on a separate 
line, then click OK. 


5 To add a new IP address and hostname, click New in the Host IP Address List section, then 
specify the IP address. In the Host Name(s) text box, specify a hostname, then click OK. 


6 To delete a host, select the check box next to the host you want to delete, then click Delete. 
7 Click OK. 
8 On the Server Configuration page, click OK, then update Access Gateway. 
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4.2.7.5 


4.2.7.6 


4.2.8 


Adding a New IP Address to Access Gateway 


Before configuring Access Gateway to use a new IP address, you must first use an operating system 
utility to add the IP address. 


After you have used a system utility to add an IP address, you need to update Access Gateway 
Service to display the new IP address as a configuration option. 

1 Click Devices > Access Gateways > [Name of Gateway Service]. 

2 On the Server Details page, click New IP > OK. 


Access Gateway scans the operating system for its configured IP addresses and adds any new 
addresses. The new address is then available for assignment on Access Gateway configuration 
pages. 


3 (Optional) To verify that the scan has completed, click the Command Status tab. 


Adding New Network Interfaces to Access Gateway Appliance 


Before you can configure Access Gateway to use a new IP address, you must first use an operating 
system utility to add the IP address. 


If you add new network interface cards to Access Gateway Appliance after installation, perform the 
following steps: 


1 Start YaST, click Network Devices > Network Card, then select the Traditional Method to 
configure the IP address. 

2 Click Devices > Access Gateways > [Name of Gateway Appliance]. 

3 On the Server Details page, click New IP, then click OK. 


Access Gateway scans the operating system for its configured IP addresses and adds any new 
addresses. Any new address is then available for assignment on Access Gateway configuration 
pages. 


4 Click Access Gateways and then click Edit for the cluster or server that has the new card. 
5 Click Adapter List. 


The newly added network interface is displayed here. Use this page to change the IP address 
related configuration. Now on, you must not use YaST. 


Enabling Access Gateway to Display Post-Authentication 
Message 


When Identity Server authentication process is completed, the user-agents are redirected to their 
originally requested URL. The originally requested URL is then retrieved by the proxy. This process 
requires SSO and authentication process of its own. As a result, retrieving the requested URL may 
take a long time. It is not clear how much time the authentication process takes and how much time 
the origin server request and authentication processes take. 


To remove this ambiguity, you can enable Access Gateway to display a message before redirecting 
the user-agent to the originally requested URL. 


To enable this enhancement, complete the following steps: 


1 Go to Devices > Access Gateways > Edit > Reverse Proxy /Authentication > ESP Global 
Options. 


2 Set IS_DISPLAY_AUTH_DONE_PAGE to true. 
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When this option is enabled, the following message is displayed before the final redirect to the 
requested URL: 


Authentication successful, please wait while your requested page loads. 


The web page that display this message is a JSP page. Location of this page is /opt/novell/nam/ 
mag/webapps/nesp/jsp/waitredir .jsp. You can perform further customization on this page. 


4.2.9 Customizing Access Gateway 


¢ Section 4.2.9.1, “Maintaining a Customized Access Gateway,” on page 325 


¢ Section 4.2.9.2, “Customizing Error Messages and Error Pages on Access Gateway,” on 
page 325 


¢ Section 4.2.9.3, “Customizing Logout Requests,” on page 328 


4.2.9.1 Maintaining a Customized Access Gateway 


If you have customized the .jsp files for Access Gateway, you must perform the following steps to 
maintain the customized files before upgrading Access Manager. If you do not, Access Manager 
overwrites the customized .jsp files. For more information, see Maintaining Customized JSP Files 
for Access Gateway in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


4.2.9.2 Customizing Error Messages and Error Pages on Access Gateway 


Access Gateway uses the custom error page template to rebrand and localize the language of error 
pages that are published to the browser. 


By default, Access Gateway contains the following files to help customize and localize the error 
messages: 


+ The error page configuration file, ErrorPagesConfig. xml 


+ The error messages file, ErrorMessages.xml.en 


NOTE: If you are modifying any of the above files, ensure that you retain the original filenames. 


Access Gateway maintains /opt/novell/nam/mag/webapps/agm/WEB- INF/config/current/ 
directory to save files that are used for error page configuration. 


You can customize and localize the error template and the error messages: 


¢ “Customizing and Localizing Error Messages” on page 325 


+ “Customizing the Error Pages” on page 326 


Customizing and Localizing Error Messages 


When Access Gateway serves an error message to the browser by using the Accept-Language 
header value received from the browser, it selects a suitable error template and an error message file. 
To localize the error messages, you must to do the following: 


Localize or customize the error messages in the ErrorPagesConfig. xml file and save it with the 
language extension. 
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The error messages contained in the ErrorMessages. xml.en file can be localized in various 
languages and stored as ErrorMessages.xml.<lang>, where </ang> is the fileXn attribute value. 
You can also customize the English error messages present in the ErrorMessages.xml.en file. 


NOTE: You cannot customize an error message that is not present in the ErrorMessages.xml.en 
file. 


To localize the error messages, perform the following steps: 


1 Login as root. 

2 Open the ErrorMessages.xml.<lang> file. 

3 Copy the error messages that you have localized or customized to within the 
<TranslatedMessage></TranslatedMessage> tags. For example: 


</Message> 
<Message id="<ID No>" name="<ERROR_MESSAGE_NAME>"" enable="yes"> 
<EnglishMessage>English Message goes here</EnglishMessage> 
<TranslatedMessage> 
Localized message goes here 
</TranslatedMessage> 
</Message> 


Do not delete the contents within the <TranslatedMessage></TranslatedMessage> tags from 
an English file because, the ErrorPagesConfig. xml file selects the error message within these 
tags for display. 


4 Save the file. 


5 If Access Gateway belongs to a cluster, copy the modified file to each member of the cluster, 
then restart that member. 


6 Edit the configuration and make dummy changes and push the configuration. 


Customizing the Error Pages 


Access Gateway uses the Apache method for localizing error messages. You can modify these 
messages or customize the page they are displayed on. 
1 To change a message: 
1a Change to the Apache message configuration directory: 
Linux: /etc/opt/novell/apache2/conf/extra 
Windows: \Program Files\Novell\apache\conf\extra 
1b Open the http-multilang-errordoc.conf file. 


The first few lines of this file contains comments on how Apache recommends modifying the 
error messages. You can select to use their method or continue with the following steps. 


1c Locate the ErrorDocument section and determine the error code message you want to 
modify. Make note of the *.var filename. 


1d Change to the Apache error directory: 

Linux: /opt/novell/apache2/share/apache2/error 

Windows: \Program Files\Novell\apache\error 
1e Open the *.var file that you want to modify. 

The message is listed alphabetically by language code. 
1 


> 


Save the changes. 
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2 To change the header of the error page: 


2a 


2b 
2c 


2d 
2e 


2 
2g 
2h 

i 


> 


Change to the Apache error include directory: 

Linux: /opt/novell/apache2/share/apache2/error/include 
Windows: \Program Files\Novell\apache\error\include 
Open the top.html page. 

To change the title of the page, locate the following line: 


<title>Access Gateway<\title> 


Replace the Access Gatewaystring with the content you require. 
To replace the image in the header, locate the following line: 


<img src="/NAGErrors/images/header_550.png" alt=""_ height="50px" 
width="550px" border="0"> 


Replace header_550.png with the filename of the image you want to display. 
Adjust the height and width values to match your image. 

Save the file. 

Copy your image to the images directory: 

Linux: /opt/novell/apache2/share/apache2/error/images 


Windows: \Program Files\Novell\apache\error\images 


3 To change the footer of the error page: 


3a 


3b 
3c 


3d 


3e 
3 


=> 


Change to the Apache error include directory: 

Linux: /opt/novell/apache2/share/apache2/error/include 
Windows: \Program Files\Novell\apache\error\include 

Open the bottom.html page. 

To change the image, find the following line: 

<td style="background-color: #E6D88C; padding-left: 10px"><img 


style="padding-right: 200px" src="/NAGErrors/images/ 
LAP_interoperable_logo_100.gif" align="absmiddle" border="0"> 


Change LAP_interoperable_logo_100. gif to the filename of the image you want to 


display. 

Save the file. 

Copy your image to the images directory: 

Linux: /opt/novell/apache2/share/apache2/error/images 


Windows: \Program Files\Novell\apache\error\images 


4 Copy all modified files and image files to all Access Gateways in the cluster. 


The err_legacy.jsp file will also log the ESP error messages. For more information on customizing 
the err_legacy.jsp page, see “Customizing Identity Server Messages” on page 274. The procedure 


for customizing is the same except the paths for Access Gateway. The following are the path 


changes: 


¢ In Customizing Identity Server Messages, the paths for Access Gateway are as follows: 


Step 3, path on Linux is /opt/novell/nam/mag/webapps/nesp/WEB- INF/1ib and on Windows 


is 


/Program Files/Novell/Tomcat/webapps/nesp/WEB-INF/1lib/. 
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4.2.9.3 


Step 10, path on Linux is /opt/novell/nam/mag/webapps/nesp/WEB- INF/classes and on 
Windows is /Program Files/Novell/Tomcat /webapps/nesp/WEB-INF/classes. 
Step 12, restart Access Gateway by running /etc/init.d/novell-mag restart. 


¢ In Customizing the Branding of the Error Page, the path for err_legacy.jsp in the ESP on 
Linux is /opt/novell/nam/mag/webapps/nesp/jsp and on Windows is /Program Files/ 
Novell/Tomcat/webapps/nesp/jsp/. 


Customizing Logout Requests 


+ “Customizing Applications to Use Access Gateway Logout Page” on page 328 
e “Customizing Access Gateway Logout Page” on page 328 


¢ “Configuring the Logout Disconnect Interval” on page 330 


Customizing Applications to Use Access Gateway Logout Page 


If any of your protected resources have a logout page or button, you need to redirect the user’s logout 
request to Access Gateway logout page. Access Gateway can then clear the user’s session and log 
the user out of any other resources that have been enabled for single sign-on. If you do not redirect 
the user’s logout request, the user is logged out of one resource, but the user’s session remains 
active until inactivity closes the session. If the user accesses the resource again before the session is 
closed, single sign-on reauthenticates the user to the resource, and it appears that the logout did 
nothing. 


1 Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication. 


2 In the Embedded Service Provider section, view the path to the AGLogout page in the Logout 
URL option. 


The Logout URL displays the URL that you need to use for logging users out of protected 
resources. This option is not displayed until you have created at least one reverse proxy with a 
proxy service. If you create two or more reverse proxies, you can select which one is used for 
authentication, and the logout URL changes to match the assigned reverse proxy. For more 
information about how to change the authentication proxy, see “Changing the Authentication 
Proxy Service” on page 173. 


3 Redirect application logout requests to the AGLogout page. 
4 Click OK. 


Access Gateway does not support the following logout pages that were used in previous version of 
Access Manager and iChain: 


+ /cmd/BM-Logout 
e /cmd/ICSLogout 


Customizing Access Gateway Logout Page 


You can create your own logout page and configure Access Gateway to use it. To do this, you need to 
modify the logoutSuccess_legacy.jsp file on Access Gateway. It is located in the following 
directory: 


Linux: /opt/novell/nesp/1lib/webapp/jsp 


Windows: \Program Files\Novell\Tomcat\webapp\nesp\jsp 
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You can modify the file to display what you want or you can modify it to redirect the user to your 
custom page. The following sections provide some tips for accomplishing this task: 

¢ “Modifying the Header’ on page 329 

¢ “Redirecting to Your Custom Page” on page 329 

¢ “Calling Different Logout Pages” on page 329 


Modifying the Header 


The logoutSuccess_legacy.jsp file is called in a frame from the nidp_legacy.jsp file. The 
branding in the header of the logout page is controlled by the branding of the nidp. jsp file. For 
information about how to modify nidp_legacy.jsp for logos, titles, and colors, see “Rebranding the 
Header” on page 260. 


IMPORTANT: Take a backup of nidp_legacy. jsp file before modifications. Every time you upgrade 
your Access Gateway, upgrade process overrides any custom changes made to JSP files that use 
the same filename as those included with the product. If you want the modified file, you need to 
restore the nidp_legacy.jsp file. During an upgrade, you can select to restore custom login pages, 
but NetIQ still recommends that you have your own backup of any customized files. 


Redirecting to Your Custom Page 


One way to provide redirection is to replace the information in the <body> element of the 
logoutSuccess_legacy.jsp file with something similar to the following: 


<body> 
<script language="JavaScript"> 
top. location. href='http://<hostname/path>' ; 
</script> 
</body> 


Replace the <hostname/path> string with the location of your customized logout page. 


IMPORTANT: Take a backup of logoutSuccess_legacy.jsp file before modifications. Every time 
you upgrade your Access Gateway, upgrade process overrides any custom changes made to JSP 
files that use the same filename as those included with the product. If you want the modified file, you 
need to restore the nidp_legacy. jsp file. During an upgrade, you can select to restore custom login 
pages, but NetIQ still recommends that you have your own backup of any customized files 


Calling Different Logout Pages 


If you need to use a different logout page for specific protected resources, you need to modify the 
logout button of the applications to use the AGLogout URL rather that the plogout URL (see 
“Customizing Applications to Use Access Gateway Logout Page” on page 328). The AGLogout page 
redirects to the plogout page, which calls the logoutSuccess_legacy. jsp. Any parameter added to 
the AGLogout or plogout URL is saved and passed to the logoutSuccess_legacy . jsp file. However, 
any parameter added to the plogout URL is saved and passed to the logoutSuccess_legacy.jsp 
file. 


The parameter passed to the logoutSuccess_legacy.jsp file can be used with if/else logic in the 
body of the page to load different custom logout pages based on the parameter value. 


To use the plogout URL, you need to modify the application’s logout button to call the following URL: 


<ESP Domain>/nesp/app/plogout 
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Replace <ESP Domain> with the same value as the AGLogout value. For example, suppose your 
AGLogout value is the following: 


https://jwilson1.provo.novell.com:443/AGLogout 

You would replace it with the following value: 
https://jwilson1.provo.novell.com:443/nesp/app/plogout 

If you add a parameter to the URL, it would look similar to the following: 


https://jwilsoni1.provo.novell.com: 443/nesp/app/plogout?app=email 


Logging Out of Sessions of Access Gateway and SAML Connectors when 
Branding Exists in the Customized Logout Page 


When you have both Liberty and SAML 2.0 sessions running on Identity Server and you log out of 
Access Gateway, the logoutSuccess_legacy.jsp page is not executed with the customizations you 
have made to the logout page. You will be able to log out of Access Gateway but the customizations 
you made are lost. 


If the logutSuccess_legacy.jsp file is not loaded in a frame, the banner will not be displayed, and 
Access Gateway will comment out the content in the logoutSuccess_legacy.jsp file. Add the below 
line after the <body> tag in the logoutSuccess_legacy. jsp file. 


<!-- BANNER LOADS IF THIS PAGE IS NOT LOADED IN REGULAR FRAME --> 


<%@include file="logoutHeader .jsp"%> 


Configuring the Logout Disconnect Interval 


When a user clicks the logout button and the user is logging out of an Access Gateway that is a 
member of a cluster, the user is not immediately disconnected from the resource. The logout 
message must be sent to each member of the cluster. The default interval for checking the pending 
logout message queue is 30 seconds. If this interval is too long, you can configure a shorter interval in 
the web. xm1 file of the Embedded Service Provider. This must be set on each Access Gateway in the 
cluster. 
1 Log in to Access Gateway as the root or administrator user. 
2 Open web.xml. 
Linux: /opt/novell/nesp/1lib/webapps/WEB- INF/web. xml 
Windows: /Program Files/Novell/nesp/1lib/webapps/WEB- INF/web. xml 
3 Find the <context-param> section in the file. 
4 Add the following parameter to the <context -param> section. 
<context -param> 
<param-name>LogoutRetirementFrequency</param-name> 


<param-value>15000</param-value> 
</context -param> 


5 Set the <param-value> element to a value between 5000 and 30000 milliseconds (5 seconds 
and 30 seconds). 
6 Restart the Embedded Service Provider. 


For information about how to restart the Embedded Service Provider from Administration 
Console, see Section 4.2.3, “Managing Access Gateways,” on page 304. 
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4.3.1 


Access Gateway Content Settings 


One of the major benefits of using an Access Gateway to protect Web resources is that it can cache 
the requested information and send it directly to the client browser rather than contacting the origin 
Web resource and waiting for the requested information to be sent. This can significantly accelerate 
access to the information. 


IMPORTANT: For caching to work correctly, the Web servers must be configured to maintain a valid 
time. If possible, they must be configured to use an NTP server. 


The object cache on an Access Gateway is quite different from a browser’s cache, which all users 
access when they click the Back button and which can serve stale content that does not’ accurately 
reflect the fresh content on the origin Web server. 


Access Gateway caching system uses a number of methods to ensure cache freshness. Most time- 
sensitive Web content is flagged by Webmasters in such a way that it cannot become stale unless a 
caching system ignores the Webmaster's settings. Access Gateway honors all RFC 2616 directives 
that affect cache freshness such as Cache-Control, If-Modified-Since, and Expires. 


Access Gateway can be fine-tuned for cache freshness in the following ways: 


+ Accelerated checking of objects that have longer than desirable Time to Expire headers 
¢ Delayed checking of objects that have shorter than desirable Time to Expire headers 
+ Checking for freshness of objects that do not include Time to Expire headers 


Both Access Gateway Appliance and Access Gateway Service follow RFC directives. In addition, 
Access Gateway Service uses the “Apache Module mod_file_cache’” (http://httpd.apache.org/docs/ 
2.2/mod/mod_file_cache.html). 


The following sections describe the features available to fine-tune this process for your network: 


¢ Section 4.3.1, “Configuring Caching Options,” on page 331 
¢ Section 4.3.2, “Controlling Browser Caching,” on page 333 
¢ Section 4.3.3, “Configuring a Pin List,” on page 333 

¢ Section 4.3.4, “Configuring a Purge List,” on page 336 

¢ Section 4.3.5, “Purging Cached Content,” on page 337 

¢ Section 4.3.6, “Apache htcacheclean Tool,” on page 337 


Configuring Caching Options 
The Cache Options allow you to control how Access Gateway caches objects. 


1 Click Access Gateways > Edit > Cache Options. 

2 To disable caching of all Web server content, select Disable Caching. 
When this option is selected, all other caching options are disabled. 

3 Configure the Cache Management options: 


Enable Caching of Objects with a Question Mark: If this option is selected, a cacheable 
object is cached if it has a question mark in the URL. 


Enable Caching of Objects with CGI in the Path: If this option is selected, a cacheable object 
is cached if it has /cgi in its URL. 
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Objects that meet these criteria are only cached if they are also cacheable objects. Web server 
administrators can mark objects as non-cacheable. When so marked, these objects are not 
cached, even when the above options are selected. 


If you disable both of these options, it does not mean that objects with question marks or cgi in 
their paths cannot be cached. These objects can match some other criteria and be cached. 


4 (Access Gateway Appliance) Configure the Cache Tuning options. 


These options restrict or enable functionality that affects all the resources protected by Access 
Gateway. 


Refresh Requests from Browser: When a user clicks Refresh or Reload in the browser, this 
action sends a new request to the Web server. Select one of the following options to control how 
Access Gateway handles the request: 


+ Refill: Causes the proxy service to send the request to the Web server. 


¢ Ignore: Causes the proxy service to ignore the request and send the data from cache 
without checking to see if the cached data is valid. 


5 Modify the Cache Freshness settings. Use the Reset button to return these settings to their 
default values. 


These options govern when the proxy service revalidates requested cached objects against 
those on their respective origin Web servers. If the objects have changed, the proxy service re- 
caches them. 


WARNING: Enter whole number values. Decimal values (2.5) are not supported and generate 
an XML validation error. 


HTTP Maximum: Specifies the maximum time the proxy service serves HTTP data from cache 
before revalidating it against content on the origin Web server. No object is served from cache 
after this value expires without being revalidated. 


This overrides a freshness or Time to Expire directive specified by the Webmasters if they 
specified a longer time. 


You use this value to reduce the maximum time the proxy service waits before checking whether 
requested objects need to be refreshed. The default is 6 hours. 


HTTP Default: Specifies the maximum time the proxy service serves HTTP data for which 
Webmasters have not specified a freshness or Time to Expire directive. The default is 2 hours. 


HTTP Minimum: (Access Gateway Appliance) Specifies the minimum time the proxy service 
serves HTTP data from cache before revalidating it against content on the origin Web server. No 
requested object is revalidated sooner than specified by this value. 


This overrides the freshness or Time to Expire directive specified by the Webmasters if they 
specified a shorter time. 


You can use this value to increase the minimum time the proxy service waits before checking 
whether requested objects need to be refreshed. This parameter does not override No Cache or 
Must Revalidate directives from the origin Web server. 


The default value is 0, which allows the proxy service to honor the Time To Expire directive of 
each object (unless it is longer than the HTTP Maximum option). If the HTTP Minimum option is 
set to a value other than 0, the value overrides any object’s Time to Expire directive that is 
shorter than the value set. The default is 0. 


Continue Fill Time: (Access Gateway Appliance) Specifies the how long the proxy service 
ignores browser request cancellations and continues downloading objects from the target Web 
server until the download is complete. The default is 1 second. 


HTTP Retries: (Access Gateway Appliance) Specifies the number of retry requests to issue to a 
Web server. The default is 4 retries. 
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4.3.2 


4.3.3 


6 To save your changes to browser cache, click OK. 
7 To apply the changes, click the Access Gateways link, then click Update > OK. 


Controlling Browser Caching 


Webmasters control how browsers cache information by adding the following cache-control directives 
to the HTTP headers: 


Cache-Control: no-store 
Cache-Control: no-cache 
Cache-Control: private 
Cache-Control: public 

Pragma: no-cache 


You can configure how the proxy service responds to these directives in the HTTP header. 
1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> HTTP Options. 


2 To mark all pages coming through this host as cacheable on the browser, select Allow Pages to 
be Cached by the Browser. 


When this option is enabled, the no-cache and no-store headers are not injected into the HTTP 
header. 


You need to select this option if you have a back-end application that updates the data in the 
Last-Modified or ETag HTTP headers. These changes are forwarded from the Web server to the 
browser only when this option is enabled. 


You need to select this option if you want the Expires HTTP header forwarded from the Web 
server to the browser. 


If this option is not selected, all pages are marked as non-cacheable on the browser. This forces 
the browser to request a resend of the data from Access Gateway when a user returns to a 
previously viewed page. 


3 By default, the Enable X-Forwarded-For option is enabled. X-Forwarded-For headers are used 
to pass browser ID information along with browser request packets. If the headers are included, 
Web servers can determine the origin of browser requests they receive. If the headers are not 
included, browser requests have anonymity. 


Apache is configured to always send the X-Forwarded-For, X-Forwarded-Host, and X- 
Forwarded-Server headers. You cannot change this behavior in Administration Console. 


4 Click OK. 
5 To apply the changes, click the Access Gateways link, then click Update > OK. 


Configuring a Pin List 


A pin list contains URL patterns for identifying objects on the Web. Access Gateway uses the list to 
prepopulate the cache, before any requests have come in for the content. This accelerates user 
access to the content because it is retrieved from a local cache rather than from an exchange with the 
Web server, which would read it from disk. 


You can use the pin list to specify the following: 


e Which objects you want to cache 
e Which objects you never want cached 
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The pin list is global to Access Gateway and affects all protected resources. The objects remain in 
cache until their normal cache limits are reached or they are bumped out by more recently requested 
objects. 


To configure a pin list: 


1 Click Devices > Access Gateways > Edit > Pin List. 


2 Select the Enable Pin List option to enable the use of pinned objects. If this option is not 
selected, the pinned objects in the pin list are not used. 


3 In the Pin List section, click New. 
4 Fill in the following fields. 


URL Mask: Specifies the URL pattern to match. For more information, see “URL Mask” on 
page 334. 


Pin Type: Specifies how the URL is to be used to cache objects. Select from Normal and 
Bypass. For more information, see “Pin Type” on page 336. 


5 To save the list item, click OK. 
6 To save your changes to browser cache, click OK. 
7 To apply the changes, click the Access Gateways link, then click Update > OK. 


URL Mask 


The URL mask can contain complete or partial URL patterns. A single URL mask might apply to a 
large set of URLs, or it might be so specific that only a single file on the Web matches it. 


Access Gateway processes the masks in the pin list in order of specificity. A mask containing a 
hostname is more specific than a mask that specifies only a file type. The action taken for an object is 
the action specified for the first mask that the object matches. 


Access Gateways recognizes four levels of specificity, using the following format: 


Level Examples 

hostname http://www. foo.gov/documents/picture. gif 
http://www. foo.gov/documents/* 
http://www. foo. gov 
foo.gov/documents/* 
foo.gov/* 


All of these are classified as hostnames, and they are ordered by specificity. The 
first item in the list is considered the most specific and is processed first. The last 
item is the most general and is processed last. 
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Level Examples 


path /documents/picture. gif 
/documents/pictures.gif/* 
/documents/* 


Path entries are processed after hostnames. A leading forward slash must always 
be used when specifying a path, and the entry that follows must always reference 
the root directory of the Web server. In these examples, documents is the root 
directory. 


The /* at the end of the path indicates that the entry is a directory. Its absence 
indicates that the entry is a file. In these examples, picture.gif isa file and 
pictures.gif/* and documents/* are directories. 


If you enter a path without the trailing *, the path matches only the directory. With the 
trailing *, the path matches everything in the directory and its subdirectories. 


These path entry examples are ordered by specificity. The objects in the / 
documents/picture.gifdirectory are processed before the objects in the / 
documents directory. 


filename /picture.gif 
/widget.js 
/widget.jp*g 
/picture*group. gif 
/DailyTask 
/DailyTask* 


Filenames are processed after paths. A leading forward slash must always be used 
when specifying a filename. 


You can add asterisks in the file names. 
file extension /* gif 

/* js 

/* Atm 


File extensions are processed last. They consist of a leading forward slash, an 
asterisk, a period, and a file extension. 


NOTE: More than one wildcard is not allowed in a URL mask. For example, /*picture.g*f is not 
correct. 


Also, the wildcard must be only in the last part of the path. For example: 
Correct: /picture/* .gif 


Incorrect: /documents/*/picture. gif 


Specific rules have precedence over less specific rules. Thus, objects matched by a more specific 
rule are always processed according to its conditions. If a less specific rule also matches the object, 
the less specific rule is ignored for the object. For example, assume the following two entries are in 
the pin list: 
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URL Mask Pin Type Pin Links 
http://www. foo.gov/documents/* normal 1 


www. foo* bypass N/A 


The first entry, because it is most specific, caches the pages in the documents directory and follows 
any links on those pages and caches the linked pages. The second entry does not affect what the first 
entry caches, but it prevents any other domain extensions such as .com, .net, or .org whose DNS 
names begin with www. foo from being cached. 


Pin Type 
The pin type specifies how Access Gateway caches objects that match the URL mask. 


¢ Normal: Access Gateway handles objects matching the mask in the same way it handles any 
other requested objects. In other words, the objects are cached but not pinned. 


Administrators often use this pin type in combination with a broad URL mask that has a bypass 
pin type. This allows them to insulate specific objects from the effects of the bypass rule. 


For example, you could specify a URL mask of /* . jpg with a pin type of bypass and a second 
URL mask of www. foo. gov/graphics/* with a pin type of normal. This causes all files, including 
. jpg files, in the graphics directory on the foo. gov Web site to be cached as requested. 
Assuming there are no other URL masks in the pin list, all other JPG graphics are not cached 
because of the /* . jpg mask. 


+ Bypass: Access Gateway does not cache the objects. In other words, you can use this option to 
prevent objects from being cached. 


4.3.4 Configuring a Purge List 


The purge list is global to Access Gateway and affects all protected resources. This option allows you 
to specify URL patterns or masks for the pages and sites whose objects you want to purge from 
cache. 


When you specify the URL mask, do not specify a port. Ports are not stored in the cache file that is 
used to match the URLs that must be purged. 


When defining the masks, keep in mind that Access Gateway interprets everything in the URL mask 
between the asterisk wildcard (*) and the following delimiter as a wildcard. Delimiters include the 
forward slash (/), the period (.), and the colon (:) characters. For example: 


URL Mask Effects 

/* pdf Causes all PDF files to be purged from cache. 

www.foo.gov/contracts/* Causes all objects in the contracts directory and beyond to be purged from 
cache. 


This option also allows you to purge cached objects whose URL contains a specified query string or 
cookie. This mask is defined by placing a question mark (?) at the start of the mask followed by text 
strings and wildcards as necessary. String comparisons are not case sensitive. For example, 
?*=SPORTS purges all objects with the text =SPORTS or any other combination of uppercase and 
lowercase letters for =SPORTS following the question mark in the URL. 
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4.3.5 


4.3.6 


IMPORTANT: If you also configure a pin list, carefully select the objects that you add to the pin and 
purge lists. Make sure you don’t configure a pin list that adds objects to the cache and a purge list that 
removes the same objects. 


1 Click Devices > Access Gateways > Edit > Purge List. 

2 Click New, enter a URL pattern, then click OK. 

3 (Optional) Repeat Step 2 to add additional URL patterns. 

4 To save your changes to browser cache, click OK. 

5 To apply the changes, click the Access Gateways link, then click Update > OK. 


Purging Cached Content 


You can select to purge the content of the purge list or all content cached on the server. 


1 Click Devices > Access Gateways. 
2 Select the name of the server, then click Actions. 
3 Select one of the following actions: 


Purge List Now: Click this action to cause all objects in the current purge list to be purged from 
the cache. 


Purge All Cache: Click this action to purge the server cache. All cached content, including items 
cached by the pin list, is purged. 


4 Click either OK or Cancel. 


When you make certain configuration changes such as updating or changing certificates, changing 
the IP addresses of Web servers, or modifying the rewriter configuration, you are prompted to purge 
the cache. The cached objects must be updated for users to see the effects of such configuration 
changes. If your Access Gateways are in a cluster, you need to manage the purge process so your 
site remains accessible to your users. You must apply the configuration changes to one member of a 
cluster. When its status returns to healthy and current, issue the command to purge its cache. Then 
apply the changes to the next cluster member. 


IMPORTANT: Do not issue a purge cache command when an Access Gateway has a pending 
configuration change. Wait until the configuration change completes. 


Apache htcacheclean Tool 


If you have caching issues with inodes, disk space, and cache corruption in Access Gateway, use 
Apache htcacheclean tool which is used to keep the size of mod_disk_cache's storage within a 
certain limit. This tool can run either manually or in daemon mode. When running in daemon mode, it 
sleeps in the background and checks the cache directories at regular intervals for cached content to 
be removed. 


The htcacheclean utility tool is located at: 

Linux: /opt/novell/apache2/sbin 

Windows: C:\Program Files\Novell\apache\bin 
The default cache location is: 


Linux: /var/cache/novell-apache2 
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4.4 


4.4.1 


Windows: C:\apache_cache_root 

Example: To clear 1024 MBytes of cache, run the following command: 
Linux: ./htcacheclean -v -t -p/var/cache/novell-apache2 -11024M 
Windows: htcacheclean.exe -v -t -pC:\apache_cache_root -11024M 


For more information about this tool, see htcacheclean - Clean up the disk cache (https:// 
httpd.apache.org/docs/2.4/programs/htcacheclean.html). 


Access Gateway Advanced Options 


Access Gateway provides the following two types of advanced options: 


+ Global options: These settings are applied to all reverse proxies, unless the option is 
overwritten by an advance proxy service level setting. The global advanced options are disabled 
by default. See Section 4.4.1, “Configuring Global Advanced Options,” on page 338. 


+ Proxy service level options: These settings are valid only for the proxy service for which you 


enable these. See Section 4.4.2, “Configuring Advanced Options for Domain-Based and Path- 
Based Multi-Homing Proxy Services,” on page 346. 


Configuring Global Advanced Options 


Perform the following steps to configure Access Gateway global advanced options: 


1 Click Devices > Access Gateways > Edit > Advanced Options. 


2 To activate these options, configure the value, save your changes, then update Access Gateway. 
To deactivate these options, add the pound (#) symbol. 


Table 4-1 Access Gateway Global Advanced Options 


Advanced Option Description 
NAGGlobalOptions Specifies whether cached credential data of the user is updated 
FlushUserCache=on when the session expires or the user changes an expiring 


password. This option is equivalent to PasswordMgmt in the 3.1 
SP4 Access Gateway Appliance. 


+ When this option is on, which is the default setting, the 
credentials and the Identity Injection data are refreshed. 


+ When this option is turned off, the cached user data can 
become stale. 


For example, if your password management service is a 
protected resource of Access Gateway and this option is turned 
off, every time a user changes an expiring password, the user’s 
data is not flushed and Access Gateway continues to use stale 
data for that user. 
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Advanced Option Description 


NAGGlobalOptions When this option is enabled, an X-Mag header is added with 

DebugHeaders=on debug information. The information can be seen in sniffer traces 
and with plug-ins such as ieHTTPHeaders, Live HTTP Headers, 
and FireBug. 


This option must only be enabled when you are working with the 
Product Support and they instruct you to enable the option. 


NAGGlobalOptions When this option is enabled, additional debug information related 
DebugFormFill=on to the processing of a Form Fill policy is added to the Apache 
error log files (error_log file under /var/log/novell- 
apachez2 for Linux and error.log file under \Program 
Files\Novell\Apache\logs for Windows) and to the X-Mag 
header in the response to browser. The Form Fill entries 
generated by this option begin with a FF: marker. 


For example, Oct 23 12:38:29 mag326 httpd[29345]: 
[warn] AMEVENTID#36: FF:fillSilent: 
kfh5ummigbq6uGeneral_SS_non_SS_autosumit_Page_1331 
0, referer: https://www. idp.com:8443/nidp/idff/ 
sso?sid=0 Oct 23 12:38:29 mag326 httpd[29345]: 
[warn] AMEVENTID#36: FF:fillInplaceSilent: 
kfh5ummigbq6uGeneral_SS_non_SS_autosumit_Page_1331 
0, referer: https://www. idp.com:8443/nidp/idff/ 


sso?sid=0 
NAGGlobalOptions Proxy starts sending errors to the browser if ESP's average 
ESP_Busy_Threshold=<value> response time in the last one minute is more than the specified 


value (time in milliseconds). 


NAGGlobalOptions noTOPR Disables the activity based time-out in proxy. The proxy redirects 
browser requests after soft timeout of configured timeout value. 


This option is equivalent to disabletoppr in the 3.1 SP4 Access 
Gateway Appliance. 


NAGGlobalOptions This enables single sign on to certain Web sites that require the 
InPlaceSilent=on login page to remain as is without any modifications to its 
structure. 


If you are using this advanced option for a Form Fill on a page 
with multiple forms, by default, the first form is posted. If you want 
to post forms other than the first form, use NAGGlobalOptions 
InPlaceSilentPolicyDoesSubmit=on. For more information, 
see TID 7011817. 


This option is equivalent to .enableInPlaceSilentFill in the 
3.1 SP4 Access Gateway Appliance. 


NAGGlobalOptions ForceUTF8 When this option is enabled, Access Gateway uses the UTF-8 
character set to serve the Form Fill page to the browser. 


This option is equivalent to forceUTF8Charset in the 3.1 SP4 
Access Gateway Appliance. 


Setting Up an Advanced Access Manager Configuration 339 


340 


Advanced Option 


NAGGlobalOptions 
AllowMSWebDavMiniRedir=on 


Description 


This option helps the user to disable the following functionality, 
which is enabled by default. If a Microsoft Network Places client 
sends an OPTIONS request with MS-WebDAV-MiniRedir 
useragent to Access Gateway, then it receives 409 conflict 
response. The client uses this response to change the user agent 
toMS Data Access Internet Publishing Provider DAV. 


For example, to access Vibe WebDav folders from My Network 
Places or Map Network Drive on Windows 7, perform the 
following steps: 


1. Set the advanced option NAGGlobalOptions 
AllowMSWebDavMiniRedir to on. 


2. On the client server, perform the following steps: 


a. Add the Vibe and Access Manager URLs to the 
browser’s trusted site and add the certificates to the 
Trusted Root Certification Authorities. 


b. Restart the client and access Vibe Webdav URLs 
either by using Add a network location option or Map 
network drive option. 


This option is equivalent to AllowMSWebDavRedir in the 3.1 SP4 
Access Gateway Appliance. 


NAGGlobalOptions 
noURLNormalize=on 


When this option is enabled, it disables the URL normalization 
protection for back-end Web servers. This option resolves issues 
in serving Web content from Web servers that have double-byte 
characters such as Japanese language characters. 


By default, this option is set to off and URL is normalized before 
sending it to back end Web server. 


NAGAdditionalRewriterScheme 
webcal:// 


When this option is enabled, the rewriter rewrites URLs that have 
a scheme of webcal://. The default rewriter configuration only 
rewrites URLs with a scheme of http:// or https: //. 


NAGGlobalOptions 
AppendProviderID=on 


When this option is enabled, it displays the ESP Provider ID in 
Access Gateway authorization audit logs. This option helps to 
know the issues related to ESP provider ID in the audit log file. 


NAGGlobalOptions 
InPlaceSilentPolicyDoesSubm 
it=on 


This option must be used to fill forms with complex JavaScript or 
VBScripts. 


This option is equivalent to .enableInPlaceSilentFillNew in 
the 3.1 SP4 Access Gateway Appliance. 


NAGGlobalOptions 
NAGErrorOnIPMismatch=of f 


In Access Manager 4.3, this option has been merged with 
Advanced Session Assurance and called as Client IP. 


For more information, see Chapter 11, “Setting Up Advanced 
Session Assurance,” on page 933. 


NAGGlobalOptions 
NAGDisableExternalRewrite=o 
n 


Access Gateway does not insert the path for the links with 
external published DNS when you enable this option. 


This option is equivalent to .disableExternalDNSRewrite in 
the 3.1 SP4 Access Gateway Appliance. 
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Advanced Option Description 


DisableGWSHealth on When this option is enabled, Access Gateway does not check 
health of the Web server with the back-end server. 


This option is equivalent to .disablewSHealth in the 3.1 SP4 
Access Gateway Appliance. 


NAGIchainCookieVersion on When this option is enabled, Access Gateway sends the proxy 
session cookie to the back-end server as IPCZQX01<clusterid>. 


IgnoreDNSServerHealth on When this option is used, Access Gateway does not send the 
DNS server health status when Access Gateway health is 
reported to Administration Console. 


When you set the option to IgnoreDNSServerHealth off 
<lookupname>, Access Gateway sends a DNS query with the 
specified <lookupname>. Access Gateway sends a successful 
message to Administration Console if it connects to the DNS 
server, else it will send an unable to connect message. By default 
if you have not specified any option, Access Gateway sets the 
option as IgnoreDNSServerHealth off www.novell.com. 


This option is equivalent to ignoreDnsServerHealth in the 3.1 
SP4 Access Gateway Appliance. 


NAGGlobalOptions Set this option to off to prevent the session ID from getting 
NAGRenameCookie=on changed automatically.By default, this option is set to on 
EnableWSHandshake on Setup a firewall between Access Gateway and the back-end Web 


server. When Access Gateway performs heartbeat check with a 
simple TCP connect to the Web server, the Web server may 
throw a TLS handshake error. This may cause the firewall, after a 
certain threshold, to block the connection. This option enables 
Access Gateway to perform a SSL handshake while performing a 
heartbeat check on the back-end SSL-enabled Web server so 
that the Web server does not respond with a TLS handshake 
error. By default, Access Gateway performs a simple TCP 
connect while performing a heartbeat check on the back-end Web 


server. 
NAGGlobalOptions This option enables the Identity Injection policy not to send an 
IIRemoveEmpt yHeader Value empty header with null value when a value is not available. By 


default, Access Gateway sends an empty header with a null value 
if a value is not available. 


For example, applications may have a public and a protected 
resource configured. Both resources may use an identity injection 
policy such as to inject an USERID. The public resource uses the 
user name if authenticated. If the user accesses the public 
resource (before authentication), Access Gateway sends an 
empty header variable USERID. Web servers may not handle an 
empty header and may respond with an error. In such a scenario 
use the advanced option to stop Access Gateway from sending 
an empty header with null value. 


DumpHeaders on These options ensure that the proxy, logs the user headers to / 
af var/opt/novell/nam/logs/mag/apache2/error_1log file for 
DumpHeadersFacility user Linux and \ProgramFiles\Novell\Apache\logs\error.log 
for Windows. 
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Advanced Option 


SSLProxyVerifyDepth=3 


Description 


Specifies how many certificates are in a Web server certificate 
chain. When you activate the verification of the Web server 
certificate with the Any in Reverse Proxy Trust Store and the 
public certificate is part of a chain, you need to specify the 
number of certificates that are in the certificate chain. 


For more information about configuring Web servers for SSL, see 
Section 17.6, “Configuring SSL between the Proxy Service and 
the Web Servers,” on page 995. 


The default search level that is when the attribute 
SSLProxyVerifyDepth is commented to1, if the number of 
certificates in the Web server certificate chain is greater than 1, 
then the SSLProxyVerifyDepth option must be enabled and 
must be assigned to the respective value (equal to the number of 
certificates in the chain). 


ProxyErrorOverride 


Allows you to specify which errors you want returned to the 
browser unchanged by the Gateway Service. The default 
behavior of the Gateway Service is to replace Web server errors 
with Gateway Service errors. 


However, some applications put more information, such as keys 
and JavaScript in the message. If this information is critical, 
specify an override and allow the error message to be returned to 
the browser without any modifications. 


For example, NetStorage requires an override for the 401 error 
because it includes a key in the 401 error. The portal page for the 
Novell Open Enterprise Server requires an override for error 403 
because it includes JavaScript. 


You can use the following syntax to set this option: 


+ ProxyErrorOverride on -401 -403:Allows all errors to 
be changed to Gateway Service errors except errors 401 
and 403, which are sent unchanged. 


This syntax allows you to list the few errors you want to 
forward without change while allowing all the others to be 
changed to Gateway Service errors. 


+ ProxyErrorOverride off +401 +403:Disables the 
changing of Web server errors to Gateway Service errors 
except for errors 401 and 403, which are changed to 
Gateway Service errors. 


Use this option when you have only a few errors that you 
want changed to Gateway Service errors. 


NOTE: Enable the error codes 401 and 403 for override if you are 
using Identity Manager 4.0 with Role Mapping Administrator. 


NAGErrorOnDNSMismatch 


If SSL is not enabled in reverse proxy, an error message stating 
Host Name Does Not Match is displayed. 
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Advanced Option 


Description 


SSLHonorCipherOrder This option enables you to customize the SSLCipherSuite used 
by Access Gateway. This helps you in taking preventive 
measures when new vulnerabilities are published. 
To avoid Browser Exploit Against SSL/TLS (BEAST) attacks, use 
the advanced option as follows: 
SSLHonorCipherOrder on 
SSLCipherSuite 
'aNULL: !eNULL: !EXPORT: !DSS: !DES:RC4-SHA:RC4- 
MD5:ALL 

NAGGlobalOptions This option enables Access Gateway to redirect based on HTTP 


onFormFillPolicyRedirUseHtt 
p=on 


status code 302 along with the location header when Form Fill 
policy requires redirect. 


By default, Access Gateway uses JavaScript to trigger redirect in 
Form Fill policy. You can use this advanced option when there are 
issues with JavaScript redirects. 


NAGGlobalOptions 
NoAuthHdrwithoutPwd=on 


This option restricts sending the authorization header with Identity 
Injection policy when a password is unavailable. For example, 
When users authenticate with Kerberos contract. 


This option is set to off by default. 


NAGLAGCompatiability on 


This option enables sharing of session information between the 
3.1 SP4 Access Gateway Appliance and the 4.0 Access Gateway 
Appliance during the process of migration. 


This option is added by default during the process of migration to 
ensure communication between the two appliances. You can 
disable or remove this option after the migration is complete. 


NAGSendURLinErrorResponses 
on 


This option will not include a href when you access a protected 
resource and a 302 redirect occurs. 


AllowEncodedSlashes When this option is enabled, URLs are accepted, but encoded 

NoDecode slashes are not decoded. 
For example, the server accepts the encoded URL 
www.example.com%2Ffinance, but does not try to decode the 
encoded slash (%2F for /). 

NAGGlobalOptions When this option is set to on, the DNS name is excluded from 


ExcludeDNSFull on 


being rewritten by that domain. The HTML Rewriting does not 
happen when the backend DNS name is included in the Exclude 
DNS Name list. 


NAGGlobalOptions 
NoAuthHdrwithoutPwd=on 


This option restricts sending the authorization header with Identity 
Injection policy when a password is unavailable. For example, 
When users authenticate with Kerberos contract. 


This option is set to off by default. 


SetStrictTransportSecurity 
off 


NOTE: This option is available in 
Access Manager 4.3 Service Pack 
1 and later versions. 
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Set this option to off if you want to disable HTTP Strict Transport 
Security. By default, it is set to on. 


343 


4.4.1.1 


Advanced Option 


NAGGlobalOptions 
SetHashedCookiesInResponse= 
on 


NOTE: This option is available in 
Access Manager 4.3 Service Pack 
1 and later versions. 


Description 


Access Manager 4.3 and later prints only the hashed values of all 
IPC and AGIDC cookies in the log files. When this advanced 
option is set to on, Access Gateway sets these hashed values of 
IPC and AGIDC cookies into browsers with the name 
IPCZQX0354154289-Hash and AGIDC0354154289- Hash. 


For more information, see Section 30.16.3, “Adding Hashed 
Cookies into Browsers,” on page 1291. 


NAGGlobalOptions 
TempUserTTL=<value in 
minutes> 


NOTE: This option is available in 
Access Manager 4.3 Service Pack 
3. 


You can add this option to extend the time limit in minutes for 
validating a web server cookie even when the IPC cookie (used 
by Access Manager to mangle the cookies after authentication) is 
not validated. 


Consider a scenario where a user is trying to access a protected 
resource for the first time and has to register user details before 
authenticating to Access Manager. In this scenario, as the Access 
Manager authentication is unsuccessful the IPC cookie gets 
invalidated resulting in invalid web server cookie. Hence, the user 
cannot access the registration page. If you enable this option with 
the required time limit, user can complete the registration 
process. 


NAGSessionkey Default 


For additional security in case of cross-domain authentication, 
Access Gateway session cookie is encrypted before sending it as 
a URL query parameter. 


For example: 


In earlier releases of Access Manager, the URL is: https: // 
novell. blr.com:9443/ - 
CIPCZQX03218a425f=01000300a463892f582b51722510f 334 
a4223149 


In Access Manager 4.1, the URL is: https: // 

novell. blr.com: 9443/%20 - 

CECCj dOOBPIqZZNtF+dR1AyDfTFvOPwn00xz0QTcnrubNzJ6GF 
e6FF8dWRzzZg7RY9IZIYXNLaU80KnJOoqtqf6u2g== 


You can use NAGSessionkey to specify the password as per the 
administrator's needs. Passwords with more characters increase 
the strength of it and increases the security. By default, the 
password is set to default. 


For example, NAGSessionKey NAM-CROSS-DOMAIN-SESSION- 
KEY -ENCRYPTION-PASSWORD. 


For the list of proxy service level advanced options, see Table 4-2 on page 346. 


Options to Clean Up Thick Client State At Browser 


When Access Gateway detects the idle timeout, the user is redirected to Identity Server for 
authentication. If the content type and URL pattern used by the client (as defined in the advanced 
options NAGUr1Pattern and NAGContentType), the user must be redirected to a pre-defined timeout 
as defined in the NAGAuthFrontChannel advanced option. The redirected URL also contains 
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4.4.1.2 


4.4.1.3 


additional information such as ESP login URL, the contract name, and the landing page URL as 
defined in the advanced options. The following advanced options must be used together to clean up 
the thick client: 


Advanced Option Description 

NAGLauncher URL that launches the client. 

NAGUr1Pattern /messagebroker/* URL pattern that identifies if a specific request came 
from a client. 

NAGContentType application/x-amf Content type in the Request header that is used to 


identify if the request is a client. 


NAGAuthBackChannel /namtimeout/timeoutamf | Timeout handler on the server. 


NAGAuthFrontChannel Timeout handler on the server which includes the 
published DNS name of the server. 


Enabling Cookie Mangling 


When you log out of Access Manager, the Access Manager session cookies is invalidated on all 
Identity Servers and Access Gateway servers. However, the application session cookie is left 
unchanged on the browser and on the origin web server. If a different user authenticates to Access 
Manager again on the same browser and accesses the proxied web server, the browser may resume 
the previously established HTTP session with the web server so that the new user inherits the old 
logged out users session. The Cookie Mangling feature in Access Gateway prevents this scenario by 
manipulating the application cookies set by the web servers, and invalidating these cookies when a 
user logs out of Access Manager. 


The two advanced Access Gateway options required to enable this functionality are NAGHostOptions 
mangleCookies and NAGWSMangleCookiePrefix. By default, the option NAGHostOptions 
mangleCookies is disabled. 


To enable this feature, add the options NAGHostOptions mangleCookies=on and 
NAGWSMangleCookiePrefix <AnyString> in the Global Advanced Option. 


Use the NAGWSMangleCookiePrefix <AnyString> option to specify the string added to the 
application cookie after manipulation. You can replace <AnyString> with a string of your choice. For 
example, adding the NAGWSMangleCookiePrefix AGMANGLE results in the Set-Cookie: 
AGMANGLEa50b_DzkN=5a8G0 application level cookie set in the browser. 


URL Attribute Filter 


This feature lets you define filtering options for each proxy service. It helps in filtering out specified 
URLs from the ones audited as part of the URL Accessed audit event. These filtered out URLs are 
not displayed in the Audit Server. This is helpful where auditing every URL is not required and may 
increase the load on the Audit Server. Unnecessary URLs such as, public images, public javascripts, 
css, and favicons can be ignored from auditing. The option to set this feature is 
NAGFilteroutUrlForAudit <regular expression>. This option must be added to the Advanced 
options section of each service. The regular expression is standard perl based regular expressions. 
For more information, see Regular Expressions (http://perldoc.perl.org/perlre.html). 


Each URL (path?querystring) is matched against this expression. If the match is successful, the URL 
will not be audited for URL access. For example, NAGFilteroutUrlForAudit ".*.jpg" and 
NAGFilteroutUrlForAudit ".*.gif". If these options are added to a service, all the *. jpg and 

* gif files accessed will not be audited under the 'URL Accessed’ audit event. 
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NOTE: Enabling URL Accessed audit events in Access Gateway can overload the Audit subsystem if 
the number of requests sent to Gateway per second is high. This may result in a delay in web pages 
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Based Multi-Homing Proxy Services 


Perform the following steps to configure the advanced options for domain-based and path-based 
multi-homing proxy service: 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> Advanced Options. 
2 Configure the advanced option by removing the pound(#) symbol. 


To disable an option, add the # symbol in front of the option, save your changes, then update 
Access Gateway. 


Table 4-2 Access Gateway Advanced Options for Proxy Services 


Advanced Option Description 
NAGHostOptions This option invalidates the cookies set by the Web server when the user 
mangleCookies=on logs out of Access Manager. By default, Access Gateway does not 


mangle the cookies that are sent by the web server. 


Proxy mangles the cookies that are sent by the web server using the 
user information and sets these mangled cookies at the browser. When 
a browser sends the mangled cookies to proxy, it de-mangles them 
using the user information and sends the de-mangled cookies to the 
web server. 


For more information about this option, see “Enabling Cookie Mangling” 
on page 345. 


NAGWSMangleCookiePrefi | Use the NAGWSMangleCookiePrefix <AnyString> option to specify 
x the string added to the application cookie after manipulation. 


For more information about this option, see “Enabling Cookie Mangling” 
on page 345. 


NAGFilteroutUrlForAudi | You can add this option to proxy service that filters out specific URLs 
t from auditing (URL Accessed). For example, 
NAGFilteroutUrlForAudit ".*.jpg", and 
NAGFilteroutUrlForAudit ".*.gif". 


CacheIgnoreHeaders Prevents Access Gateway from writing any Authorization headers to 

: a , disk. This option is enabled by default, because writing Authorization 
This option is available only | headers to disk is a potential security risk. You can allow Authorization 
for the domain-based proxy headers to be written to disk by placing a pound (#) symbol in front of 
service. the option or by setting it to None. 


For more information about this Apache option, see 
“CachelgnoreHeaders Directive” (http://httpd.apache.org/docs/2.2/mod/ 
mod_cache.html#cacheignoreheaders). 


NOTE: All the path-based services under the domain-based service will 
inherit the new value. 
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CacheMaxFileSize 


This option is available only 
for domain-based proxy 
service. 


Description 


Configuring this option in the Advanced Options of a proxy service 
allows you to set the size of the file that can be stored in the cache. By 
default the size is set to 5 MB. Add the line CacheMaxFileSize <bytes>, 
for example, CacheMaxFileSize 99900000. 


NOTE: All the path-based services under the domain-based service will 
inherit the new value. 


NAGChildOptions 
WebDav=/Path 


This option is valid only for 
path-based multi-homing 
proxy service. 


Allows the proxy service to handle the specified path. Remove the 
pound (#) symbol and replace /Path with the path you want the proxy 
service to handle. 


ProxyPassIgnorePathCas 
e on 


Use this option to make the path-based multi-homing path URL case- 
insensitive. For example, if you have set up a path based proxy /profile 
in Administration Console and the end user wants to access the URL 
https://www.lagssl.com/Profile/Security/login.aspx and not https:// 
www.lagssl.com/profile/Security/login.aspx. By default, the URL path is 
case-sensitive. 


NAGPostParkingSizeInKki 
loBytes 


This option allows you to change the post data parking size limit if an 
error occurs after you post large data (more than 56 Kilobytes in size) 
after a session timeout. 


SSLProtocol 


This option is supported by Access Gateway when listening as a server 
to clients (typically browsers). This directive specifies SSL protocols for 
mod_ssl to use when establishing the server environment. Clients can 
only connect with one of the specified protocols. The accepted values 
are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and all of these. 


The syntax for this is SSLProtocol [+-]protocol. For example, 
SSLProtocol +SSLv3. For more information about configuring the SSL 
versions, see Apache documentation. 


SSLProxyProtocol 


This option is supported by Access Gateway when the reverse proxy is 
connecting to the backend web servers. This directive specifies SSL 
protocols for mod_ssl to use when establishing a proxy connection in 
the server environment. Proxies can only connect with one of the 
specified protocols. The accepted values are SSLv3, TLSv1, TLSv1.1, 
TLSv1.2 and all of these. 


The syntax for this is SSLProxyProtocol [+-]protocol. For 
example, SSLProxyProtocol +SSLv3. For more information about 
configuring the SSL versions, see Apache documentation. 


For Windows: 
SSLProxyCACertificateF 
ile "C:\Program 
Files\Novell\apache\ca 
certs\myserver.pem" 


For Linux: 
SSLProxyCACertificateF 
ile /opt/novell/ 
apache2/cacerts/ 
myserver.pem. 


This option prevents failure in SSL connection between Access 
Gateway and webserver, when a self-signed certificate is used. To 
prevent this, import the webserver certificates to the proxy trust store. 
After importing, the webserver certificates, use this advanced option. 


Setting Up an Advanced Access Manager Configuration 


347 


348 


Advanced Option 


FailOnStatus error 
code1,error code 
2,error code3 


Description 


Back-end servers may return an error code instead of being timed out. 
Access Gateway keeps sending requests to a web server, even if the 
web server returns error codes. 


To prevent sending Access Gateway requests to such web servers, you 
can use this advanced option. 


AdditionalBalancerMemb 
erOptions 


The proxy server checks the web server for each new session request 
at an interval of one minute by default. You can configure this advanced 
option to specify a different interval. 


For example, specify AdditionalBalancerMemberOptions 
retry=180, where 180 is in seconds. 


You can set the following parameters for this option: 
+ min 
+ max 
+ smax 
+ acquire 
+ connectiontimeout 
+ disablereuse 
+ flushpackets 
+ flushwait 
* ping 
+ loadfactor 
+ redirect 
+ retry 


+ status 


For more information about these parameters, see Apache Module 
mod_proxy. 


The following parameters are not supported: 


keepalive, lbset, route, timeout, and ttl 


RWOutboundHeaderQueryS 
tring on 


This option enables outbound header query string rewriting. 


NAGAddProxyHeader on 


When this option is set to off, Access Gateway will not send the 
XForwarded Headers to the back-end web server. 


By default, this option is set to on. 


NAGHostOptions 
DisableIDC on 


This disables Advance Session Assurance for small lived session IDs. 
Set to off to enable Advance Session Assurance for session ID. 


For more information, see “Disabling Advanced Session Assurance for 
Access Gateway Proxy Services” on page 939. 
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NAGHostOptions 
DisableSFP on 


Description 
This disables server-side fingerprinting Session Assurance. 
Set to off to enable server-side fingerprinting Session Assurance. 


For more information, see “Disabling Advanced Session Assurance for 
Access Gateway Proxy Services” on page 939. 


NAGHostOptions 
primaryWebdav=<path of 
pbmh service> 


This option is valid only for 
the path-based multi-homing 
proxy service. 


This option enables users who use the Microsoft Network Places client 
to connect to the WebDAV folders of a SharePoint server when the 
SharePoint server has been configured as a path-based multi-homing 
service on Access Gateway. This must be added to master proxy 
service Advanced Options whose path based child services 
accelerates webdav resources with remove path on fill option enabled. 


This option is equivalent to .modifyRequestURI in the 3.1 SP4 Access 
Gateway Appliance. 


NAGHostOptions 
webdavPath=/_vti_bin 


This option is valid only for 
the path-based multi-homing 
proxy service. 


This can be added to master proxy service Advanced Options which 
path based child services with remove path on fill option enabled 
accelerating webdav resources. 


NAGChildOptions 
WebDav=<path of pbmh 
service> 


This option is valid only for 
the path-based multi-homing 
proxy service. 


This option can be added to any path based service that accelerates 
webdav resources with remove path on fill enabled. 


This option is equivalent to .modifyRequestURI in the 3.1 SP4 Access 
Gateway Appliance. 


For the list of global advanced options, see Table 4-1 on page 338. 


4.5 Analytics Server Configuration 


This section describes the configuration settings that affects the Analytics server, such as changing 
its name, updating the health status from the server, and restarting it. 


+ 


+ 


+ 


Section 4.5.1, “Managing Analytics Server,” on page 350 


Section 4.5.2, “Managing General Details of Analytics Server,” on page 351 


Section 4.5.3, “Analytics Server Cluster Configuration,” on page 352 


Section 4.5.4, “Managing Details of a Cluster,” on page 352 


Section 4.5.5, “Configuring Analytics Server,” on page 353 


Section 4.5.6, “Forwarding Events from Sentinel Server to Analytics Server,” on page 354 


Section 4.5.7, “Importing Analytics Server,” on page 356 
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4.5.1 


4.5.1.1 


Managing Analytics Server 


The following sections contain information about settings available with Analytics Server, changing 
the settings, and their impact on users: 


¢ Section 4.5.1.1, “Viewing Server Settings,” on page 350 
¢ Section 4.5.1.2, “Configuration Options,” on page 351 


Viewing Server Settings 


Use the Analytics Servers page to view the status of Analytics Server, to view the health, and to 
perform other actions such as creating a cluster or stopping, refreshing, and starting Analytics Server. 


1 Click Devices > Analytics Server. 


2 Select one of the following: 


Analytics-Cluster: To create a new cluster of Analytics Server, click Analytics-Cluster. A cluster 
can be one or more Analytics Server machines. 


For configuration information, see “Configuring Analytics Server” on page 353. 


Stop: To stop an Analytics Server, select the server, then click Stop. You must have physical 
access to the Analytics Server machine to start it again. 


Restart: To reboot an Analytics Server machine, select the machine name, then click Restart. 
Analytics Server is stopped, the operating system reboots, then the machine is started. 


Refresh: To update the list of Analytics Server machines and the status columns (Status, 
Health), click Refresh. 


To perform the delete action available in the Actions drop-down menu, select Analytics Server, 
then select the following: 


Delete: To remove the selected Analytics Server from the list of servers that can be managed 
from this Administration Console. If that Analytics Server is a member of a cluster, you must first 
disable the cluster configuration before you can delete it. 


IMPORTANT: When an Analytics Server is deleted from an Administration Console, you can no 
longer manage it. To access it again or to access it from another Administration Console, you 
must manually import Analytics Server by running reimport_ar.sh in the /opt/novell/nam/ 
scripts directory. For more information about re-importing Analytics Server, see Section 4.5.7, 
“Importing Analytics Server,” on page 356. 


Use the following to manage an Analytics Server machine or a cluster. 


Name: Displays a list of Analytics Server machines and the clusters that can be managed from 
Administration Console. 


+ To view or modify the general details of a particular server, click the name of the server. 
+ To view or modify general details of a cluster, click the name of the cluster. 


Status: Indicates the configuration status of the clusters and Analytics Server. Possible states 
are pending, update, current, and update all. For more information, see “Configuration Options” 
on page 351. 
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4.5.1.2 


4.5.2 


Health: Indicates whether an Analytics Server machine or a cluster is functional. Click the icon 
to view additional information about the operational status of an Analytics Server. 


¢ For information about the health of a specific Analytics Server machine, click the health icon 
on the Analytics Server row. For more information, see Section 24.5, “Monitoring the Health 
of Analytics Server,” on page 1107. 


+ For information about the health of an Analytics Server cluster, click the health icon on the 
cluster row. For more information, see Section 24.5.2, “Monitoring the Health of Analytics 
Server Cluster,” on page 1108. 


Commands: Indicates the status of the last executed command and whether any commands 
are pending. Click the link to view more information. For more information, see Section 23.3, 
“Viewing the Command Status of the Analytics Server,” on page 1096. 


Configuration Options 


1 In Administration Console Dashboard, click Devices > Analytics Server. 
2 View the Status column and make changes as necessary. 


Status Description 
Current Indicates that all configuration changes are applied. 
Update Indicates that a configuration change is made, but not applied. To apply the 


changes, click the Update link. 


Update All This link is available when a server belongs to a cluster. You can select to 
update all the servers at the same time, or you can select to update them one 
at a time. We recommend that you update the servers one at a time. 


Update [! | If there is an error when you update the server, the Update link is disabled and 
the Configuration Error icon is displayed. 


Update All |! | If there is an error when you click Update All, the member Update links are 
disabled and the Configuration Error icon is displayed. 


Pending Indicates that the server is processing a configuration change, but has not 


completed the process. 


3 Configure Analytics Server settings by using the steps mentioned in Section 4.5.5, “Configuring 
Analytics Server,” on page 353. 


NOTE: To view the graphs on Analytics dashboard you must enable the respective events in Identity 
Server and Access Gateway. For information about enabling required events, see Section 18.5, 
“Enabling Events for Each Graph,” on page 1003. 


Managing General Details of Analytics Server 


The Server Details page allows you to perform general maintenance action on the selected Analytics 
Server. 


1 Click Devices > Analytics Server > [Name of Analytics Server]. 
2 Click Edit. 
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4.5.3 


4.5.4 


To edit the general details of Analytics Dashboard, see “Changing the Name of an Analytics 
Server and Modifying Other Server Details” on page 352. 


3 Click Close. 


Changing the Name of an Analytics Server and Modifying Other 
Server Details 
The default name of an Analytics Server is its IP address. You can change this to a more descriptive 
name and modify other details that can help you identify one Analytic Server from another. 

1 Click Devices > Analytics Server > [Name of Analytics Server] > Edit. 

2 Modify the values in the following fields: 


Name: Specify the Administration Console display name for Analytics Server. This is a 
mandatory field. The default name is the IP address of Analytics Server. If you modify the name, 
the name must include alphanumeric characters and can include spaces, hyphens, and 
underscores. 


Management IP Address: Specify the IP address that is used for managing Analytics Server. 
It is recommended not to change this IP address. 
Port: Specify the port to use for communication with the Administration Console. 


Location: Specify the location of Analytics Server. This is optional, but useful if your network has 
multiple Analytics Server machines. 


Description: Describe the purpose of this Analytics Server. This is optional, but useful if your 
network has multiple Analytics Server. 


3 Click OK > Close. 
When you click OK, changes are immediately applied to Analytics Server. 


Analytics Server Cluster Configuration 


To use the cluster with high availability, you must perform the steps mentioned for “Deploying 
Analytics Server for High Availability” in NetlQ Access Manager 4.3 Installation and Upgrade Guide. 


NOTE: After following the steps for deploying Analytics Server for high availability, you can view both 
Active and Standby nodes. To use Analytics Server in high availability mode, you must enable cluster 
configuration in Administration Console. 


There can be only two servers in an Analytics Server high availability cluster. Both servers will use the 
virtual IP address that you create after installing Analytics Server in cluster mode. This IP address is 
an external IP address for Analytics server. 


The following sections describe how to set up and manage a cluster of Analytics Server. 


Managing Details of a Cluster 


1 Click Devices > Analytics Server > Analytics-Cluster. 
2 Specify the following details: 
Cluster Name: Specify a display name for the cluster. 


Primary Server: Specify the IP address of the primary server. The Access Manager reports and 
Analytics Dashboard are displayed from this server. 
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NOTE: When you change the IP address in Primary Server, the Secure Logging Server settings 
are changed. Hence, you must configure Syslog for auditing again. For more information about 
configuring the settings, see Section 19.1.2, “Configuring Syslog for Auditing,” on page 1019. 


3 In the Server Name list, select the server that you want to add as a member of the cluster. 
You can create a cluster of one additional server. 


When you add a server to the cluster, it adds about 30 seconds to the time it takes to configure 
the cluster because certificates must be synchronized and configuration options must be sent to 
that server. 


4 Click OK. 


4.5.5 Configuring Analytics Server 


The configuration page allows you to view the configuration of a cluster or an Analytics Server 
machine. You can specify the log level and also configure the geolocation provider either for a 
particular server or for a cluster. The Analytics server uses this information to generate logs and 
reports. 


To configure the settings for Analytics Server or a cluster, perform the following in Administration 
Console: 

1 Click Devices > Analytics Server. 

2 In the cluster row, click Edit. 

3 In the Log level field, select the required log level from the list. 


Log level Description 

severe Sends only messages that render the system unusable, if they are not 
resolved. 

warning Sends warning messages. 

info Sends informational messages such as requests sent to Web servers 


and the results of authentication requests. 


debug Sends debug messages 


4 In the Geolocation Provider field, click the edit icon. 


5 Select Enable Location Profiling to fetch location data from a geolocation database. This helps 
to identify the location of the user based on the IP address details. 


6 Select a Geolocation Provider. The available options are: 


Database Details 


Neustar Service + Specify the API Key and API Secret. 
+ Specify the Web Service URL. 


Custom Provider + Specify a name to identify the provider. 
+ Specify the fully qualified name of the JAVA class. 


+ Click Add Property to add properties to the custom class. 


Analytics Dashboard uses this detail to plot the Geolocation of Users graph. 
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7 (Conditional) If you have deployed Analytics Server for high availability, then in the Cluster 
Configuration section, set the Clustering is Configured: field to Yes and specify the same virtual 
IP address in the Cluster’s Virtual IP: field that you had specified during installation. For more 
information, refer NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


NOTE: You cannot disable the high availability configuration. Even when you set the Clustering 
is Configured: field to No, the cluster configuration for active and standby nodes remains 
unchanged. 


When you set this field to No, the virtual IP address is not used and you have to change the 
server details for auditing. For more information about changing the server details for auditing, 
see Section 19.1.1, “Specifying the Logging Server and Console Events,” on page 1017. 


4.5.6 Forwarding Events from Sentinel Server to Analytics Server 


If you have an existing audit server as Sentinel Server and require a graphical view of Access 
Manager events by using Analytics Dashboard, then you can forward the audit events from Sentinel 
Server to Analytics Server by using Sentinel link connector. 


When Analytics Server is installed and configured, Access Manager displays the following message: 


Analytics Server will be functional only when it is set as the Audit Server. 


If you want to continue using Sentinel server as the audit server, then you can ignore this message. 
To view the graphical view of the audit events in Analytics Dashboard you can perform the following 


steps: 


To forward the events you must perform the following: 


1 Configure Analytics Server to receive events. 


la 
1b 
1c 
1d 
le 
1f 
1g 
1h 
li 
1j 


1k 
1 


im 
in 


Log in to Access Manager Administration Console 

Click Devices > Analytics Server > Reports 

Log in to Analytics Server with the Analytics Server administrator credentials 
Click admin > Applications 

Click Launch Control Center 

Click Event Source Management > Live view 

Click on the Table tab, then click the expand symbol (+) next to Sentinel 
Right click Sentinel Server, then click Add Event Source Server 

Select Sentinel Link from the installed connectors list, then click Next 


Configure network settings by specifying Port Number for Event Source Server, then click 
Next. The default port is 1290 


Continue with the default configuration for Security and Auto Configuration 
In the General dialog box, select the Run icon 


This allows the connector to run on 1290 so that Sentinel Server can connect with Analytics 
Server. 


Click Finish 


Click the expand symbol (+) next to Sentinel Server and verify if the status of Sentinel Link 
Server All:<port number> is On 
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2 Configure Sentinel Server to send events to Analytics Server. 
2a Update the latest NetIQ Access Manager Collector in Sentinel Server 
2b Log in to the Sentinel Control Center with administrator rights 
2c Click the Configuration tab to enable Configuration on the menu bar 
2d Click Configuration, then select Integrator Manager 
2e Click the Add Integrator (+) icon to configure Integrator plug-in 
2 
2g Specify a name for the integrator in the Name field 
2h Click Next 
2i 


> 


Select the Sentinel Link Integrator from the Select Integrator drop-down list 


In the Server Configuration dialog box, specify the Host Name as the IP address of 
Analytics Server 


2j Specify the port number to connect to Analytics Server 
The default port is 1290. 


2k Click Next to continue with the default configurations, then click Test configuration to verify 
the connection is successful. 


21 Click OK > Finish 
3 Add an Action by using Sentinel Action Manager 


3a Navigate to control center > configuration > Action Manager 
3b Click Add 
3c In the Configure Action dialog box, specify the following: 
+ Action Name: any name 
+ Action: Sentinel Link 
+ Name: Integrator 
e Value: Select the same integrator name that you have specified in Step 2g. 
3d Click Save 


4 In Sentinel Server, create a routing rule to enable default routing that sends events automatically 
to Analytics Server 


4a Log in to Sentinel Server 

4b On the main menu, click Routing 

4c Click Edit next to Forward Events To Another Sentinel System 
4d Specify the following: 


+ Criteria: (((sev:[0 TO 5]) NOT st:"I" NOT st:"A" NOT st:"P") AND ("NIDS\: 
User session was authenticated" OR evt:"NIDS\: Risk based 
authentication action for user" OR rv40:"002E0606" OR rv40:"002E0525" 
OR rv40:"002E001F" OR rv40:"002E0029" OR rv40:"002E0514" OR 
rv40:"002E0102" OR rv40:"002E000C") ) 


+ Route to the following services: All 


+ Perform the following actions: Specify the action name that you specified during the 
configuration of Action Manager in Step 3. 


4e Click Save 
Ensure that the routing rule is enabled. 
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4.5.7 Importing Analytics Server 


If you want to import Analytics Server to any Administration Console, you must run the re-import 
script on the required Analytics Server. 


To import or re-import Analytics Server to a specific Administration Console, perform the following on 
the required Analytics Server: 


1 Go to the directory: /opt/novell/nam/scripts 


cd /opt/novell/nam/scripts 


2 Run the sh reimport_ar.sh script and enter the details against the following 


prompts: 

2a Choose a local listener IP address [x.x.x.x]: 

2b (Optional) Choose a local NAT IP address [optional]: 
2c Choose Administration Console’s IP address []: 


Specify the IP address of the Administration Console on which you want to import the 
Analytics Server. 


2d Enter Admin User’s DN [cn=admin,o=novell]: 


2e Enter Admin Password: ***** 


3 Wait for few minutes for the configuration to finish. 


4.6 Modifying Configuration Files 


You can modify configuration files such as server.xml and web.xml to set up various configurations. 


4.6.1 Modifying web.xml 


You can modify the web. xm1 file to perform the following configurations: 


+ 


Configuring the Encryption Method for the SAML Assertion. For information about how to 
configure it, see “Configuring the Encryption Method for the SAML Assertion” on page 909. 


Configuring SAML 2.0 to Sign Messages. For information about how to configure it, see “Access 
Manager Services That Use the Signing Certificate” on page 912. 


Managing Administration Console Session Timeout. For information about how to configure it, 
see Section 2.2, “Managing Administration Console Session Timeout,” on page 43. 


Configuring the Logout Disconnect Interval. For information about how to configure it, see 
“Configuring the Logout Disconnect Interval” on page 330. 


Disabling User Profile Objects. For information about how to configure it, see “Disabling User 
Profile Objects” in the NetIQ Access Manager 4.3 Best Practices Guide. 


Configuring a Specific IP Address for Proxied Requests. For information about how to configure 
it, see “Configuring a Specific IP Address for Proxied Requests” in the NetIQ Access Manager 
4.3 Best Practices Guide. 


Disabling Phishing For information about how to configure it, see “Disabling Phishing” in the 
NetIQ Access Manager 4.3 Security Guide . 
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4.6.2 Modifying server.xml 


You can modify the server . xml file to perform the following configurations: 


+ Changing the IP Address of an Identity Server. For information about how to configure it, see 
Section 2.4.2, “Changing the IP Address of an Identity Server,” on page 52. 


¢ Configuring a Protected Identity Server Through Access Gateways. For information about how to 
configure it, see Section 3.11, “Configuring a Protected Identity Server Through Access 
Gateways,” on page 220. 


¢ Customizing Certificate Errors. For information about how to configure it, see “Customizing 
Certificate Errors” on page 402. 


¢ Configuring X.509 Authentication to Provide Access Manager Error Message. For information 
about how to configure it, see “Configuring X.509 Authentication to Provide Access Manager 
Error Message” on page 403. 


¢ Forcing 128-Bit Encryption. For information about how to configure it, see “Forcing 128-Bit 
Encryption” on page 908. 


¢ Securing the Embedded Service Provider Session Cookie on Access Gateway. For information 
about how to configure it, see “Securing the Embedded Service Provider Session Cookie on 
Access Gateway” on page 928. 


¢ Enabling a Windows SSL Renegotiation. For information about how to configure it, see 
“Enabling a Windows SSL Renegotiation” on page 989. 


¢ Configuring the SSL Communication. For information about how to configure it, see “Configuring 
the SSL Communication” on page 996. 


¢ Restoring the Configuration on a Standalone Administration Console. For information about how 
to configure it, see “Restoring the Configuration on a Standalone Administration Console” on 
page 1132. 


¢ Protecting Administration Console. For information about how to configure it, see “Restricting 
Administration Console Access to only Private Network’ in the NetIQ Access Manager 4.3 
Security Guide .Configuring the 256-bit and Higher Ciphers for SSL Communication. For 
information about how to configure it, see “Optimizing SSL Configuration with Ciphers” in the 
NetIQ Access Manager 4.3 Security Guide .Specifying SSL Configuration for Identity Server. 


¢ For information about how to configure it, see “Configuring a Specific IP Address for Proxied 
Requests” in the NetIQ Access Manager 4.3 Best Practices Guide. 
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D Configuring Authentication 


5.1 


Identity Server is responsible for authenticating users, building the user’s role information, and 


distributing it to various components. It also serves as the central point for components that request 


identity information. 
This part discusses how to configure various types of authentications. Topics include: 


¢ Section 5.1, “Local Authentication,” on page 359 

¢ Section 5.2, “Federated Authentication,” on page 428 

¢ Section 5.3, “Advanced Authentication,” on page 645 

¢ Section 5.4, “Social Authentication,” on page 652 

¢ Section 5.5, “Risk-based Authentication,” on page 658 
You can configure third-party authentication classes. You can also write your own Java class for 
authentication. For information about how to write your own class, see NetIQ Access Manager 4.3 


Developer Guide and Access Manager Developer Tools and Examples (https://www.netiq.com/ 
documentation/access-manager-43-developer-documentation/). 


Local Authentication 


To guard against unauthorized access, Access Manager supports a number of ways for users to 
authenticate. These include name/password and X.509 digital certificates. You configure 
authentication at Identity Server by creating authentication contracts that Access Manager 
components (such as an Access Gateway) can use to protect a resource. 


Figure 5-1 illustrates the components of a contract: 


Figure 5-1 Local Authentication 
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¢ User stores: The user directories to which users authenticate on the back end. You set up your 


user store when you create an Identity Server cluster configuration. See Section 5.1.1, 
“Configuring Identity User Stores,” on page 360. 


+ Classes: The code (a Java class) that implements a particular authentication type (name/ 


password, RADIUS, and X.509) or means of obtaining credentials. Classes specify how Identity 


Server requests authentication information, and what it must do to validate those credentials. 
See Section 5.1.2, “Creating Authentication Classes,” on page 370. 


+ Methods: The pairing of an authentication class with one or more user stores, and whether the 
method identifies a user. See Section 5.1.3, “Configuring Authentication Methods,” on page 377. 
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¢ Contracts: The basic unit of authentication. Contracts can be local (executed at the server) or 
external (satisfied by another Identity Server). Contracts are identified by a unique URI that can 
be used by Access Gateways and agents to protect resources. Contracts are comprised of one 
or more authentication methods used to uniquely identify a user. You can associate multiple 
methods with one contract. See Section 5.1.4, “Configuring Authentication Contracts,” on 
page 379. 


This section explains the following: 


¢ Section 5.1.1, “Configuring Identity User Stores,” on page 360 

¢ Section 5.1.2, “Creating Authentication Classes,” on page 370 

¢ Section 5.1.3, “Configuring Authentication Methods,” on page 377 

¢ Section 5.1.4, “Configuring Authentication Contracts,” on page 379 

¢ Section 5.1.5, “Specifying Authentication Defaults,” on page 387 

¢ Section 5.1.6, “Persistent Authentication,” on page 389 

¢ Section 5.1.7, “Client Integrity Check,” on page 391 

¢ Section 5.1.8, “Mutual SSL (X.509) Authentication,” on page 399 

¢ Section 5.1.9, “ORed Credential Class,” on page 404 

¢ Section 5.1.10, “OpenID Authentication,” on page 405 

¢ Section 5.1.11, “Password Retrieval,” on page 406 

¢ Section 5.1.12, “Configuring Access Manager for NESCM,” on page 408 
¢ Section 5.1.13, “Kerberos Authentication,” on page 412 

¢ Section 5.1.14, “Managing Direct Access to Identity Server,” on page 424 
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User stores are LDAP directory servers to which end users authenticate. You must specify an initial 
user store when creating an Identity Server configuration. You use the same procedure for setting up 
the initial user store, adding a user store, or modifying an existing user store. 

1 Click Devices > Identity Servers > Servers > Edit > Local. 

2 Select from the following actions: 


New: To add a user store, click New. For configuration information, see “Configuring the User 
Store” on page 361. 


Delete: To delete a user store, select the user store, then click Delete.The user store list needs 
to contain at least one configured user store for Identity Server to be functional. 


Modify: To modify the configuration of an existing user store, click the name of a user store. For 
configuration information, see “Configuring the User Store” on page 361. 


3 Click OK, then update Identity Server if you have modified the configuration. 
See the following sections for specific configuration tasks: 


¢ Section 5.1.1.1, “Using More Than One LDAP User Store,” on page 361 

¢ Section 5.1.1.2, “Configuring the User Store,” on page 361 

¢ Section 5.1.1.3, “Configuring an Admin User for the User Store,” on page 364 
¢ Section 5.1.1.4, “Configuring a User Store for Secrets,” on page 364 
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5.1.1.2 


Using More Than One LDAP User Store 


You can configure Identity Server to search more than one user store during authentication. Figure 5- 
2 illustrates this type of configuration. 


Figure 5-2 Multiple LDAP Directories 
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It is assumed that each LDAP directory contains different users. You must ensure that the users have 
unique names across all LDAP directories. If both directories contain a user with an identical name, 
the name and password information discovered in the search of the first directory is always used for 
authentication. You specify the search order when configuring the authentication method. 


When users are added to the configuration store, objects are created for Access Manager profiles. If 
you delete a user from the LDAP directory, orphaned objects for that user remain in the configuration 
store. 


If you add a secondary Administration Console and you have added replicas to the user store of the 
primary Administration Console, ensure that you also add the replicas to the secondary 
Administration Console. 


All user stores that you add are included in health checks. If health problems are found, the system 
displays the user store on the Health page and in the trace log file. 


Configuring the User Store 


1 Click Devices > Identity Servers > Servers > Edit > Local. 
2 In the User Stores list, click New or the name of an existing user store. 

If you are creating an Identity Server configuration, this is Step 3 of the wizard. 
3 Fill in the following fields: 

Name: The name of the user store for reference. 


Admin Name: The distinguished name of the admin user of the LDAP directory, or a proxy user 
with specific LDAP rights to perform searches. For the LDAP extension to work, the proxy user 
requires write rights on the ACL. Administrator-level rights are required for setting up a user 
store. This ensures read/write access to all objects used by Access Manager. For more 
information about this user, see “Configuring an Admin User for the User Store” on page 364. 
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Each directory type uses a slightly different format for the DN: 
¢ eDirectory: cn=admin,ou=users,o=novell 
+ Active Directory: cn=Administrator,cn=users,dc=domeh,dc=test,dc=com 
or cn=john smith,cn=users,dc=domeh,dc=test,dc=com 
¢ Sun ONE: cn=admin,cn=users,dc=novell,dc=com 


Admin Password and Confirm Password: Specify the password for the admin user and 
confirm it. 


Directory Type: The type of LDAP directory. You can select eDirectory, Active Directory, or 
Sun ONE. If you have installed an LDAP server plug-in, you can select the custom type that you 
have configured it to use. For more information, see “LDAP Server Plug-In” in the NetlQ Access 
Manager 4.3 Developer Guide. 


If eDirectory has been configured to use Domain Services for Windows, eDirectory behaves like 
Active Directory. When you configure such a directory to be a user store, its Directory Type must 
be set to Active Directory for proper operation. 


Install NMAS SAML method: (eDirectory only) Extends the schema on the eDirectory server 
and installs an NMAS method. This method converts Identity Server credentials to a form 
understood by eDirectory. This method is required if you have installed Novell SecretStore on the 
eDirectory server and you are going to use that SecretStore for Access Manager secrets. If you 
select this option, ensure that the admin you have configured for the user store has sufficient 
rights to extend the schema and add objects to the tree. 


For additional configuration steps required to use secrets, see “Configuring a User Store for 
Secrets” on page 364. 


Enable Secret Store lock checking: (eDirectory only) Enables Access Manager to prompt 
users for a passphrase when secrets are locked. 


+ If Access Manager is sharing secrets with other applications and these applications are 
using the security flag that locks secrets when a user’s password is reset, you need to 
enable this option. 


+ If Access Manager is not sharing secrets with other applications, the secrets it is using are 
never locked, and you do not need enable this option. 


Under LDAP timeout settings, specify the following: 
LDAP Operation: Specify how long in seconds a transaction can take before timing out. 


Idle Connection: Specify how long in seconds before connections begin closing. If a connection 
has been idle for this amount of time, the system creates another connection. 


To specify a server replica, click New, then fill in the following fields: 


For an eDirectory server, you must use a replica of the partition where the users reside. Ensure 
that each LDAP server in the cluster has a valid read/write replica. One option is to create a 
users partition (a partition that points to the OU containing the user accounts) and reference this 
server replica. 


Name: The display name for the LDAP directory server. If your LDAP directory is replicated on 
multiple servers, use this name to identify a specific replica. 


IP Address: The IP address of the LDAP directory server. 


Port: The port of the LDAP directory server. Specify 389 for the clear text port, and 636 for the 
encrypted port. 


Use secure LDAP connections: Specifies that the LDAP directory server requires secure 
(SSL) connections with Identity Server. 
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This is the only configuration we recommend for the connection between Identity Server and the 
LDAP server in a production environment. If you use port 389, usernames and passwords are 
sent in clear text on the wire. 


This option must be enabled if you use this user store as a Novell SecretStore User Store 
Reference in the Credential Profile details. (See “Configuring Credential Profile Security and 
Display Settings” on page 523.) If you have specified that this user store is a SecretStore User 
Store Reference, this option is enabled but not editable. 


Connection limit: The maximum number of pooled simultaneous connections allowed to the 
replica. Valid values are between 5 and 50. How many you need depends upon the speed of 
your LDAP servers. If you modify the default value, monitor the change in performance. Larger 
numbers do not necessarily increase performance. 


Click Auto import trusted root. 


7 Click OK to confirm the import. 


10 


12 


13 


Select one of the certificates in the list. 


You are prompted to choose either a server certificate or a root CA certificate. To trust one 
certificate, choose Server Certificate. Choose Root CA Certificate to trust any certificate signed 
by that certificate authority. 


Specify an alias, then click OK. 
Click OK in the Specify server replica information dialog box. 


Select the replica, then click Validate to test the connection between Identity Server and the 
replica. 


The system displays the result under Validation Status. The system displays a green check 
mark if the connection is valid. 


(Optional) To add additional replicas for the same user store, repeat Step 5 through Step 11. 


Adding multiple replicas adds load balancing and failover to the user store. Replicas must be 
exact copies of each other. 


For load balancing, a hash algorithm is used to map a user to a replica. All requests on behalf of 
that user are sent to that replica. Users are moved from their replica to another replica only when 
their replica is no longer available. 


Add a search context. 
The search context is used to locate users in the directory when a contract is executed. 


+ Ifa user exists outside of the specified search context (object, subtree, one level), Identity 
Server cannot find the user, and the user cannot log in. 


+ If the search context is too broad, Identity Server might find more than one match, in which 
case the contract fails, and the user cannot log in. 


For example, if you allow users to have the same username and these users exist in the 
specified search context, these users cannot log in if you are using a simple username and 
password contract. The search for users matching this contract would return more than one 
match. In this case, you need to create a contract that specifies additional attributes so that the 
search returns only one match. For more information about how to create such contracts, see 
“Authentication Classes and Duplicate Common Names” on page 1204. 


IMPORTANT: For Active Directory, do not set the search context at the root level and set the 
scope to Subtree. This setting can cause serious performance problems. It is recommended that 
you set multiple search contexts, one for each top-level organizational unit. 


14 Click Finish. 
15 If prompted to restart Tomcat, click OK. Otherwise, update Identity Server. 
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Configuring an Admin User for the User Store 


Identity Server must log in to each configured user store. It searches for users, and when a user is 
found, it reads the user's attributes values. When you configure a user store, you must supply the 
distinguished name of the user you want Identity Server to use for logging in. You can use the admin 
user of your user store, or you can create a specialized admin user for the this purpose. When 
creating this admin user, you need to grant the following rights: 


+ The admin user needs rights to browse the tree, so Identity Server can find the user who is trying 
to authenticate. The admin user needs browse rights to object class that defines the users and 
read and compare rights to the attributes of that class. When looking for the user, Identity Server 
uses the GUID and naming attributes of the user class. 


Directory Object Class GUID Attribute Naming Attribute 
eDirectory User guid cn 
Active Directory User objectGUID sAMAccountName 
Sun ONE inetOrgPerson nsuniqueid uid 


+ The admin user needs read rights to any attributes used in policies (Role, Form Fill, Identity 
Injection, ). 


¢ Ifa secret store is used in Form Fill policies, the admin user needs write rights to the attributes 
storing the secrets. 


+ Ifa password management servlet is enabled, the admin user needs read rights to the attributes 
controlling grace login limits and remaining grace logins. 


+ If you use an LDAP extension, the user must have write rights on ACL allowing the user to check 
for account locks, password expiration, grace logins used, and so on. 


To perform these operations, the user must have additional rights. Access Manager uses NMAS 
that requires the user to have write rights on ACL. 


¢ If you enable provisioning with the SAML or Liberty protocols, the admin user needs write rights 
to create users in the user store. 


+ If you use X.509 authentication, the admin user needs write rights to update the user’s login 
status attributes. 


If your user store is an eDirectory user store, Access Manager verifies that the admin user has 
sufficient rights to browse for users in the specified search contexts. 


IMPORTANT: This check is not performed for Active Directory or Sun ONE. If your users cannot log 
in, you need to verify that you have given the admin for the user store sufficient rights to the specified 
search contexts. 


Configuring a User Store for Secrets 


Access Manager allows you to securely store user secrets. Secrets are a way to capture user input 
like Login ID and password credentials. These input data can later be reused or injected using Form 
Fill and Identity Injection policies. This feature is especially helpful when your Access Manager 
Credential Profile does not contain credentials for an application protected by Access Manager yet a 
single sign-on experience is required. Where and how the secrets can be stored is configurable and 
depends upon your user store: 


¢ “Configuring the Configuration Datastore to Store Secrets” on page 365. 
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If you want to do minimal configuration, you can use the configuration datastore on 
Administration Console to store the secrets. This option can be used without changes, but is 
recommended only for use in small Access Manager environments. To increase the security of 
the secrets, NetIQ recommends that you change the default security options. 


IMPORTANT: Using this option will put additional load on your Administration Console and 
introduces login delays compared to other options. Therefore it is recommended that this option 
is used wisely. 


“Configuring an LDAP Directory to Store the Secrets” on page 366. 


This is the recommended option and can be used with any LDAP directory. To use this option, 
extend the schema to add an attribute to your user object on the LDAP directory that will encrypt 
and store the secrets. 


“Configuring an eDirectory User Store to Use SecretStore” on page 367. 


If your user store is eDirectory and you have installed Novell SecretStore, you can choose to use 
the SecretStore on your eDirectory server to store the secrets. This differs from the schema 
extension method as Novell SecretStore can also be accessed and managed by Novell 
SecureLogin. This allows secrets to be shared with SecureLogin to provide a thick client single 
sign-on while Access Manager can provide a web single sign-on experience without credential 
collisions. 


For troubleshooting tips, see “Troubleshooting the Storing of Secrets” on page 369. 


Configuring the Configuration Datastore to Store Secrets 


When you use the configuration datastore of Administration Console as the secret store, the 
nidswsfss attribute of the nidsLibertyUserProfile object is used to store the secrets. 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 
2 Click Credential Profile. 
3 Scroll to the Local Storage of Secrets section and configure the following security options: 


Encryption Password Hash Key: (Required) Specify the password that you want to use as a 
seed to create the encryption algorithm. To increase the security of the secrets, we recommend 
that you change the default password to a unique alphanumeric value. 


IMPORTANT: Before using Access Manager to store and encrypt secrets, ensure that you 
choose your Preferred Encryption Method and change the default Encryption Password Hash 
Key value. If either of these options are changed after any secrets are stored, Access Manager 
will not be able to retrieve the secrets. 


Preferred Encryption Method: Specify the preferred encryption method. Select the method 
that complies with your security model: 

+ Password Based Encryption With MD5 and DES: MD5 is an algorithm that is used to 
verify data integrity. Data Encryption Standard (DES) is a widely used method of data 
encryption that uses a private key. 

¢ DES: Data Encryption Standard (DES) is a widely used method of data encryption that uses 
a private key. Like other private key cryptographic methods, both the sender and the 
receiver must know and use the same private key. 


¢ Triple DES: A variant of DES in which data is encrypted three times with standard DES, 
using two different keys. 


Extended Schema User Store References: Do not specify a user store reference. When this 
option contains no values, the configuration datastore is used to store the secrets. 
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4 Click OK. 
5 On Identity Servers page, update Identity Server. 


6 To use the secret store to store policy secrets, see Section 8.5.4, “Creating and Managing 
Shared Secrets,” on page 853. 


Configuring an LDAP Directory to Store the Secrets 


When you use an LDAP directory to store the secrets, you need to enable the user store for the 
secrets. You select the LDAP directory, then specify an attribute. The attribute you specify is used to 
store an XML document that contains encrypted secret values. This attribute must be a single-valued 
case ignore string that you have defined and assigned to the user object in the schema. 


To use an LDAP directory to store secrets, your network environment must conform to the following 
requirements: 


+ The user class object must contain an attribute that can be used to store the secrets. This 
attribute must be a string attribute that is single valued and case ignore. 


+ The user store must be configured to use secure connections (click Devices > Identity Servers > 
Edit > Local > User Stores > [User Store Name]. In the Server replicas section, ensure that the 
Port is 636 and that Use SSL is enabled. If they aren't, click the name of the replica and 
reconfigure it. 


To configure the LDAP directory: 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Providers. 
2 Click Credential Profile. 
3 Scroll to the Local Storage of Secrets section and configure the following options: 


Encryption Password Hash Key: (Required) Specifies the password that you want to use as a 
seed to create the encryption algorithm. To increase the security of the secrets, we recommend 
that you change the default password to a unique alphanumeric value. 


Preferred Encryption Method: Specifies the preferred encryption method. Select the method 
that complies with your security model: 


+ Password Based Encryption With MD5 and DES: MD5 is an algorithm that is used to 
verify data integrity. Data Encryption Standard (DES) is a widely used method of data 
encryption that uses a private key. 


¢ DES: Data Encryption Standard (DES) is a widely used method of data encryption that uses 
a private key. Like other private key cryptographic methods, both the sender and the 
receiver must know and use the same private key. 


¢ Triple DES: A variant of DES in which data is encrypted three times with standard DES, 
using two different keys. 


IMPORTANT: Before using Access Manager to store and encrypt secrets, ensure that you 
choose your Preferred Encryption Method and change the default Encryption Password Hash 
Key value. If either of these options are changed after any secrets are stored, Access Manager 
will not be able to retrieve the secrets. 


4 To specify where to store secret data, click New under Extended Schema User Store References 
and fill in the following: 


User Store: Select the user store where you want secret store enabled. 


Attribute Name: Specify the LDAP attribute that you have created to store the secrets on the 
selected user store. 


5 Click OK twice. 
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6 On Identity Servers page, update Identity Server. 


7 To create policies that use the stored secrets, see Section 8.5.4, “Creating and Managing 
Shared Secrets,” on page 853. 


For troubleshooting information, see “Troubleshooting the Storing of Secrets” on page 369. 


Configuring an eDirectory User Store to Use SecretStore 


For Access Manager to use Novell SecretStore, the user store must be eDirectory and Novell 
SecretStore must be installed there. When configuring this user store for secrets, Access Manager 
extends the eDirectory schema for an NMAS method. This method converts authentication 
credentials to a form understood by eDirectory. For example, Access Manager supports smart card 
and token authentications, and these authentication credentials must be converted into the username 
and password credentials that eDirectory requires. This allows Identity Server to authenticate as that 
user and access the user’s secrets. Without this NMAS method, Identity Server is denied access to 
the user’s secrets. 


To use a remote SecretStore, your network environment must conform to the following requirements: 


+ The eDirectory server must have Novell SecretStore installed. 


+ When you configure a user store to use Novell SecretStore, the admin user that you have 
configured for the user store must have sufficient rights to extend the schema on the eDirectory 
server, to install the SAML NMAS method, and set up the required certificates and objects. For 
more information about the rights required, see “Configuring an Admin User for the User Store” 
on page 364. 


+ The user store must be configured to use secure connections (click Access Manager > Identity 
Servers > Edit > Local > User Stores > [User Store Name]. In the Server replicas section, 
ensure that the Port is 636 and that Use SSL is enabled. If they aren't, click the name of the 
replica and reconfigure it. 


NOTE: While configuring new replicas for the same user store, by default the Use secure LDAP 
connections option will be selected and the default port will be 636. The Use secure LDAP 
connections option will be non-editable. 


¢ If you have enabled a firewall between Administration Console and the user store, and between 
Identity Server and the user store, ensure that both LDAP ports (389 and 636) and the NCP port 
(524) are opened. 


¢ If you are going to configure Access Manager to use secrets that are used by other applications, 
you need to plan a configuration that allows the user to unlock a locked SecretStore. See 
“Determining a Strategy for Unlocking the SecretStore” on page 368. 


To configure the user store: 


1 Click Devices > Identity Servers > Edit > Local. 
2 Click the name of your user store. 
3 Select Install NMAS SAML method, then click OK. 


This installs a required NMAS method in the eDirectory schema and adds required objects to the 
tree. 


IMPORTANT: If your eDirectory user store is running on SLES 11 SP1 64-bit operating system 
(or a higher version), the eDirectory server is missing some support libraries that this SAML 
method requires. For information about installing these libraries, see TID 7006437 (http:// 
www.novell.com/support/viewContent.do?externalld=7006437 &sliceld=1). 
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Click Liberty > Web Service Providers. 
Click Credential Profile. 


Scroll to the Remote Storage of Secrets section. 
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Click New under Novell Secret Store User Store References. 
This adds a reference to a user store where SecretStore has been installed. 


io} 


Click the user store that you configured for SecretStore. 
9 Click OK twice. 

10 On Identity Servers page, update Identity Server. 

11 Continue with one of the following: 


+ If other applications are using the secret store, you need to determine whether Access 
Manager users need the option to unlock the secret store. See “Determining a Strategy for 
Unlocking the SecretStore” on page 368. 


¢ To create policies that use the stored secrets, see Section 8.5.4, “Creating and Managing 
Shared Secrets,” on page 853. 


+ For troubleshooting information, see “Troubleshooting the Storing of Secrets” on page 369. 


Determining a Strategy for Unlocking the SecretStore 


When an administrator resets a user's password, secrets written to the Novell SecretStore with an 
enhanced security flag become locked. Identity Server does not write the secrets that it creates with 
this flag, but other applications might: 


¢ If Access Manager is not sharing secrets with other applications, the secrets it is using are never 
locked, and you do not need to configure Access Manager to unlock secrets. 


+ If Access Manager is sharing secrets with other applications and these application are using the 
security flag that locks secrets when a user’s password is reset, you need to configure Access 
Manager so that users can unlock their secrets. 


If you want users to receive a prompt for a passphrase when secrets are locked, complete the 
following configuration steps: 
1 Require all users to set up a passphrase (also called the Master Password). 


Access Manager uses the SecretStore Master Password as the passphrase to unlock the 
secrets. If the user has not set a passphrase before the SecretStore is locked, this feature of 
Access Manager cannot unlock the SecretStore. If it is necessary to unlock the SecretStore by 
using the user’s prior password, another tool must be used. See your SecretStore 
documentation. 


2 Configure Identity Server to perform the check: 
2a Click Devices > Identity Servers > Edit > Local > [User Store Name]. 
2b Select the Enable Secret Store lock checking option. 
2c Click OK twice, then update Identity Server. 
3 Ensure that Web Services Framework is enabled: 
3a Click Devices > Identity Servers > Edit > Liberty > Web Services Framework. 
3b In the Framework General Settings section, ensure that Enable Framework is selected. 
3c Click OK. If you made any changes, update Identity Server. 
4 Continue with Section 8.5.4, “Creating and Managing Shared Secrets,” on page 853. 
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When the SecretStore is locked and the users log in, the users are first prompted for their login 
credentials, then prompted for the passphrase that is used to unlock the SecretStore. 


Troubleshooting the Storing of Secrets 


¢ “Secrets Are Not Stored in Novell SecretStore” on page 369 
e “Users Are Receiving Invalid Credential Messages” on page 370 
¢ “Secrets Are Not Stored in the LDAP Directory” on page 370 


Secrets Are Not Stored in Novell SecretStore 


When you use Novell SecretStore to store the secrets, the schema on the eDirectory server must be 
extended, and specific SAML objects and certificates must be created. 


To verify that the schema was extended and the objects were created on the eDirectory server: 


1 Open an LDAP browser and connect to the LDAP server. 
2 Browse to the Security container. 
3 Look for objects similar to the following: 


P? 


eDirectory Tree 


Security 


AuthorizedLogin Methods <AffiliateObjectName> Trusted Root 


SAML Assertion E» 
Certificates 


<SAML_Affiliate_Object> 
al 


authsam|lCertContainerDN 
authsaml|TrustedCertDN 
authsamlValidAfter 
authsamlValidBefore 
authsam|ProviderlD 


If the schema has been extended correctly, you can find a SAML Assertion object in the 
Authorized Login Methods container. The SAML_Assertion object contains an alphanumeric 
generated name for a SAML affiliate object. This object has four attributes. 


The SAML affiliate object name is used to generate another container in the Security container. 
This new container is the <AffiliateObjectName> Trusted Root container that contains public key 
signing certificate. 


4 Complete one of the following: 
+ If these objects do not exist, verify the following, then continue with Step 5: 


+ The admin user for the user store has sufficient rights to extend the schema and add 
these objects to the Security container. 
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¢ Any configured firewalls must allow NCP and LDAP traffic for Administration Console, 
Identity Server, and the LDAP user store. 


¢ (Linux) Verify that you have installed the required packages. See Installation 
Requirements on Windows in the Installation Requirements on Linux and Installation 
Requirements on Windows in the NetIQ Access Manager 4.3 Installation and Upgrade 
Guide. 


+ If the objects exist, check for time synchronization problems. For more information, see 
“Users Are Receiving Invalid Credential Messages” on page 370. 


5 In Administration Console, modify the secret store configuration so that it is resent to the user 
store: 


5a Click Devices > Identity Servers > Edit > Liberty > Web Service Providers > Credential 
Profile. 


5b In the Remote Storage of Secrets section, remove the user store, then add it again. 
5c Click OK. 
6 On Identity Servers page, update Identity Server. 


Users Are Receiving Invalid Credential Messages 


The <SAML_Affiliate_Object>.SAML-Assertion.AuthorizedLoginMethods.Security object contains 
two attributes that determine how long credentials are valid. If your Identity Server and eDirectory 
server are not time synchronized, the credentials can become invalid before a user has time to use 
them. 


Either ensure that the time of your Identity Server and eDirectory server are synchronized, or 
increase the value of the authsamlValidAfter and authsamlValidBefore attributes of the SAML affiliate 
object. 


Secrets Are Not Stored in the LDAP Directory 


1 Open an LDAP browser and connect to the eDirectory server. 
2 Browse to the user object. 


3 Verify that the user object contains the LDAP attribute that you have specified as the attribute to 
store the secrets. 


4 Ifthe attribute exists, browse to the schema and verify that the attribute has the following 
characteristics: 


¢ Single valued 
+ Case ignore 
¢ String 


Creating Authentication Classes 


Authentication classes let you define ways of obtaining end user credentials. You specify the code 
(Java class) and properties to be executed to implement a particular authentication type. 


Several authentication classes are included with Access Manager to provide a variety of ways to 
authenticate end users. Custom authentication classes provided by other vendors can also be 
configured to run in the system. 

1 Click Devices > Identity Server > Edit > Local > Classes. 


The following classes are predefined for Access Manager: 
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Introductions: When the class is configured, it allows users to select an identity provider from a 
list of introducable identity providers. For information about how to configure and use this class, 
see “Configuring the Introductions Class” on page 179. 


Name/Password - Basic: Basic authentication over HTTP using a standard login pop-up page 
provided by the Web browser. 


Name/Password - Form: Form-based authentication over HTTP or HTTPS. 


Secure Name/Password - Basic: Basic authentication over HTTPS using a standard login 
page provided by the Web browser. 


Secure Name/Password - Form: Form-based authentication over HTTPS. 


Trust Levels: When this class is configured, it defines authentication levels for classes that can 
be used in authentication requests. For more information about how to configure and use this 
class, see “Configuring the Trust Levels Class” on page 180. 


2 To delete a class, select the class, then click Delete. 
You cannot delete a class if a method is using it. 


For information about how to create a name/password class, see the following sections: 


e “Creating Basic or Form-Based Authentication Classes” on page 371. 

¢ “Specifying Common Class Properties” on page 373 
Some classes require additional configuration to enable their use for authentication. See the following 
sections: 

¢ “RADIUS Authentication” on page 647 

e “Mutual SSL (X.509) Authentication” on page 399 

+ “ORed Credential Class” on page 404 

¢ “OpenID Authentication” on page 405 

+ “Password Retrieval” on page 406 

¢ “Configuring Access Manager for NESCM” on page 408 

¢ “Kerberos Authentication” on page 412 

e “Two-Factor Authentication Using Time-Based One-Time Password” on page 645 

¢ “Risk-based Authentication” on page 658 


5.1.2.1 Creating Basic or Form-Based Authentication Classes 


1 Click Devices > Identity Server > Edit > Local > Classes. 
2 Click New to launch the Create Authentication Class Wizard. 
3 Specify a display name, then select a class from the Java class drop-down menu. 
+ The following classes are recommended only for testing purposes: 
BasicClass: Uses basic HTTP authentication. 


PasswordClass: Passes the user name and password over HTTP in readable text, and 
uses a form-based login to collect the name and password. 


RadiusClass: RADIUS enables communication between remote access servers and a 
central server. For a production environment, use ProtectedRadiusClass. 


+ Fora production environment, select one of the following protected classes: 


X509Class: Certificate-based authentication. See Section 5.1.8, “Mutual SSL (X.509) 
Authentication,” on page 399. 
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SocialAuthClass: The authentication class used for implementing authentication through 
external OAuth providers such as Facebook, GooglePlus, LinkedIn and Twitter. See 
Section 5.4, “Social Authentication,” on page 652. 


TOTPClass: The authentication class used for implementing two-factor authentication. See 
Section 5.3.1, “Two-Factor Authentication Using Time-Based One-Time Password,” on 
page 645. 


Risk-based Auth Class: The authentication class used for assessing the risk after 
authentication. See Section 5.5, “Risk-based Authentication,” on page 658. 


Risk-based Pro-Auth Class: The authentication class used for assessing the risk before 
authentication. See Section 5.5, “Risk-based Authentication,” on page 658. 


ProtectedBasicClass: BasicClass protected by HTTPS. 
ProtectedPasswordClass: PasswordClass protected by HTTPS (form-based). 


ProtectedRadiusClass: RadiusClass protected by HTTPS. See Section 5.3.2, “RADIUS 
Authentication,” on page 647 for configuration steps. 


KerberosClass: The authentication class used for using Kerberos for Active Directory and 
Identity Server authentication. See Section 5.1.13, “Kerberos Authentication,” on page 412 
for configuration steps. 


NMASAuthClass: The authentication class used for Novell Modular Authentication 
Services (NMAS), which uses fingerprint and other technology as a means to authenticate a 
user. For instructions on using the NUAS NESCM method, see Section 5.1.12, “Configuring 
Access Manager for NESCM,” on page 408. 


NPOrRadiusOrxX509Class: The authentication class that allows the creation of a contract 
from which the user can select an authentication method: name/password, RADIUS, or 
X.509. For configuration information, see Section 5.1.9, “ORed Credential Class,” on 
page 404. 


PasswordFetchClass: The authentication class that allows Identity Server to retrieve the 
user’s password when the user has used a non-password class for authentication. For 
configuration information, see Section 5.1.11, “Password Retrieval,” on page 406. 


PersistentAuthClass: The authentication class that allows for persistent logins, long 
authentication sessions, or remember my password functionality. For configuration 
information, see Section 5.1.6, “Persistent Authentication,” on page 389. 


Other: Used for third-party authentication classes or if you have written your own Java 
class. For information about how to write your own class, see Novell Access Manager 
Developer Tools and Examples (https:/Awww.netiq.com/documentation/access-manager-43- 
developer-documentation/). 


AliasUserPasswordClass: This class supports authentication of a user against user's 
alias name. This class uses the alias object of the user object and the password of the 
corresponding user object to authenticate. 


Advanced Authentication: The authentication classes that support Advanced 
Authentication (for example, Email OTP, FIDO U2F). For configuration information, see 
Section 3.5.9, “Specifying Advanced Authentication Server Details,” on page 105. 


IMPORTANT: To enable CSRF check, perform the steps mentioned in “LOGIN CSRF 
CHECK” on page 77 and add a property AntiCSRFCheck=true to the class. You do not 
need to add this property to Password Class and TOTP Class. 


NOTE: You cannot enable CSRF check for Advanced Authentication class and Social 
Authentication class. 
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4 Click Next to configure the properties for each class. Click New, then enter a name and value. 
The names and values you enter are case sensitive. See “Specifying Common Class Properties” 
on page 373 for the properties that are used by the basic and password classes. 


5 Click Finish. 
6 Continue with Section 5.1.3, “Configuring Authentication Methods,” on page 377. 
To use an authentication class, the class must have one or more associated methods. 


Specifying Common Class Properties 


The following properties can be used by the basic and password classes: 


+ “Query Property” on page 373 

e “JSP Property” on page 374 

e “MainJSP Property” on page 375 

¢ “Modifying LDAP Query Parameter of Kerberos Method” on page 375 
+ “Enabling reCAPTCHA” on page 375 


These properties can also be specified on a method derived from the class. If you are going to create 
multiple methods from the same class, consider the following conditions: 


¢ If you want the methods to share the same properties, you can save configuration steps by 
defining the properties on the class. 


¢ If you want the methods to use different values for the properties such as one method specifying 
one custom login page and another method specifying a different custom login page, then you 
must specify the properties on the method. 


Query Property 


Normally, Identity Server uses the username to find a user in the user store. You can change this 
behavior by using the Query property. This property determines the username value for 
authentication. The default Query string prompts the users for the value of the CN attribute. You can 
modify this by requesting a different attribute in the LDAP query. 


The Query property can be used by the following classes: 


+ BasicClass 

e PasswordClass 

+ ProtectedBasicClass 

+ ProtectedPasswordClass 


For example, to query for the user’s UID attribute to use for the username, you would specify the 
following query: 


Property Name: Query 
Property Value: (&(objectclass=person) (uid=%Ecom_User_ID%) ) 


The values are case sensitive. The name of the property must be Query with an initial capital. The 
%Ecom_User_ID% variable is used in the default login. jsp for the username in the four classes that 
support the Query property. The variable is replaced with the value the user enters for his or her 
username, and the LDAP query is sent to the user store to see if the user’s attribute value matches 
the entered value. You can specify any attribute for the Query that is defined in your user store for the 
object class of person and that is used to identify the user. 
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The Query you define for the BasicClass and the ProtectedBasicClass needs to use an attribute that 
your users define as their username. The PasswordClass and the ProtectedPasswordClass do not 
have this requirement. They also support the JSP property, which allows you to specify a custom 
login.jsp and have it prompt for other attributes that can be used for login. 


The LDAP query parameter of Kerberos method can be modified using SearchQuery property. For 
example if you want to use the SearchQuery property for emails, perform the following steps: 
1 Navigate to Identity Servers > Edit > Local > Methods 
2 Click Kerberos Method 
3 Click Properties > New 
4 In the Add Property dialog box, specify the following: 
Property Name: SearchQuery 
Property Value: (&(objectclass=person) (mail=%Email%) ) 


For example, you can define the following Query to prompt the users for their email address rather 
than their username. 


Property Name: Query 
Property Value: (&(objectclass=person) (email=%EMail Value%) ) 


The %EMail Value% must match the variable in the custom login page that is filled in when the users 
enter their credentials. The objectclass value must be a valid object class in the LDAP user store. 
The email attribute must be a valid attribute of the person class. 


When you specify such a Query, you must also modify the login page to prompt the user for the 
correct information. Instead of prompting the user for a username, the login form must prompt the 
user for an e-mail address. The JSP Property allows you to specify a custom login page. For 
information about creating a custom login page, see “Customizing Identity Server Login Page” on 
page 256. 


JSP Property 


The JSP property allows you to specify a custom login page. This property can be used with the 
following classes: 


+ PasswordClass 
+ ProtectedPasswordClass 


The property name is JSP and the property value is the filename of the login page you customized 
without the .jsp extension of the file. The property value cannot contain nidp in its name. 


For example, if you created a custom file named emaillogin. jsp, you would specify the following 
values. The values are case sensitive. The property name needs to be entered as all capitals. 


Property Name: JSP 
Property Value: emaillogin 


If you use two methods to create a contract, this property must be set to the same value on both or 
set on only one. When it is set on only one method, the value is applied to both. This property needs 
to be used with the MainJSP Property. For information about how to create a custom login page, see 
“Customizing Identity Server Login Page” on page 256. 
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When the MainJSP property is set to true, it indicates that you want to use the page specified in the 
JSP property for the login page. When this property is set to false, which is the default value, the 
nidp.jsp is used for the login page. If you use two methods to create a contract, this property must 
be set to the same value on both or set on only one. When it is set on only one method, the value is 
applied to both. 


Property Name: MainJSP 
Property Value: true 


For information about how to create a custom login page, see “Customizing Identity Server Login 
Page” on page 256. 


Modifying LDAP Query Parameter of Kerberos Method 


The LDAP query parameter of Kerberos method can be modified using SearchQuery property. For 
example if you want to use the SearchQuery property for emails, perform the following steps: 
1 Navigate to Identity Servers > Edit > Local > Methods 
2 Click Kerberos Method 
3 Click Properties > New 
4 In the Add Property dialog box, specify the following: 
Property Name: SearchQuery 
Property Value: Specify one of the following parameters: 
+ (&(objectclass=person) (mail=%Email%) ) 
+ (&(objectclass=person) (givenName=%AMTEST .COM%) ) 
+ (&(objectclass=person) (name=%Ecom_User_ID%) ) 
) 


+ (&(objectclass=person) (CN=%Ecom_User_ID%) ) 


Enabling reCAPTCHA 


reCAPTCHA helps you to protect your user login page against spam, malicious registrations, and 
other forms of attack where bots or malicious software pretend as humans to access your computer. 
reCAPTCHA can help you secure Access Manager against attacks such as denial-of-service (DoS) 
and brute-force, which can impact the system performance to a large extent. 


reCAPTCHA provides an additional layer of security by requesting users to confirm that they are not 
a robot. It displays images that users must select based on a matching criteria. If a response 
succeeds, Access Manager authenticates the user’s authentication credentials. If a response fails, 
Access Manager does not authenticate the user credentials, and redirects to the login page. Software 
bots typically cannot scan the images to provide a response. 


Access Manager supports the latest No CAPTCHA reCAPTCHA version of the reCAPTCHA. For 
more information, see Google reCAPTCHA. reCAPTCHA works on both: Name/Password — Form 
and Secure Name/Password — Form authentication. 


The following sections provide information about configuring reCAPTCHA: 


e “Prerequisites” on page 376 
¢ “Configuring Intrusion Detection for Failed Logins” on page 376 
¢ “Setting Up a reCAPTCHA Account” on page 377 
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+ “Configuring reCAPTCHA” on page 377 
¢ “Enabling reCAPTCHA in Login Page” on page 377 


Prerequisites 
Ensure that you meet the following prerequisites before configuring the reCAPTCHA: 
+ One or more supported identity sources: 


reCAPTCHA supports Active Directory, and eDirectory. It does not support other types of identity 
sources, such as Microsoft SQL Server or Oracle Database type identity sources that use the 
JDBC identity source connector. 


Each identity source should be configured with an intrusion detection policy. For more 
information, see “Configuring Intrusion Detection for Failed Logins” on page 376. 

+ A Google reCAPTCHA account. For more information, see “Setting Up a reCAPTCHA Account” 
on page 377. 


Configuring Intrusion Detection for Failed Logins 


Someone who attempts to use more than a few unsuccessful passwords while trying to log on to your 
system might be a malicious user. reCAPTCHA cannot prevent attacks by malicious users who can 
read the image. It cannot differentiate between malicious users and legitimate users. reCAPTCHA 
cannot prevent coordinated human DoS attacks. 


To prevent brute-force or human attacks that bypass the reCAPTCHA protection, you should enable 
the user’s identity source to respond to this type of potential attack by disabling the user account for a 
preset period of time after a specified number of failed logon attempts. 


The supported identity sources have the following built-in intrusion detection systems: 


Active Directory Account Lockout Policy: Active Directory allows you to specify an account 
lockout policy for users and global security groups in a domain. Set the policy on the domain group 
policy object from the domain controller. 


To configure the Account Lockout Policy settings: 
1 Log in as an Active Directory administrator user to the Windows Server that hosts Active 
Directory Domain Services (the domain controller). 
2 Configure the Account Lockout Policy on the group policy object for the domain controller. 
For more information, see the Account Lockout Policy in Microsoft TechNet Library. 


3 Verify that the Account Lockout Threshold value is higher than the number of failed login 
attempts you plan to specify for Start reCAPTCHA at in the reCAPTCHA tool. 


4 Repeat these steps for each configured Active Directory identity source. 


eDirectory Intruder Lockout Policy: eDirectory allows you to enable intruder detection and specify 
an Intruder Lockout policy for the container object where your user objects reside. 


To configure eDirectory Intruder Detection and Intruder Lockout Policy: 


1 Log in as the eDirectory administrator user to the eDirectory server management console. 


2 Configure Intruder Detection and the Intruder Lockout policy on the container object where your 
user objects reside. 


For more information, see Setting Up Intruder Detection for All Users in a Container in the 
eDirectory 9.0 Administration Guide. 
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3 Verify that the Intruder Lockout value is higher than the number of failed login attempts you plan 
to specify for Start reCAPTCHA at in the reCAPTCHA tool. 


4 Repeat these steps for each configured eDirectory identity source. 


After you have configured intrusion detection for the supported identity sources, continue with 
“Setting Up a reCAPTCHA Account” on page 377. 


Setting Up a reCAPTCHA Account 
Before configuring reCAPTCHA, you must set up a reCAPTCHA account. 
To set up an account, perform the following steps: 


1 Log in to the Google reCAPTCHA website. 

2 Click Get reCAPTCHA > Sign up Now. 

3 Specify a label and the registered domains. 

4 Click Register. 

5 Make a note of Site Key and Secret Key for future use. 
6 Continue with “Configuring reCAPTCHA” on page 377. 


Configuring reCAPTCHA 
To configure reCAPTCHA, perform the following steps: 
1 Click Devices > Identity Server > Servers > Edit > Local > Classes > Name/Password - Form 
OR Secure Name/Password - Form. Click Properties. 
2 Select Enable reCAPTCHA. 


3 Specify the threshold value. It is the number of failed attempts before you are prompted for 
reCAPTCHA authentication. 


4 Specify the value that you noted down when setting up your reCAPTCHA account, for the 
following fields: 


¢ Site Key 
+ Secret Key 
For more information, see “Setting Up a reCAPTCHA Account” on page 377. 
5 Click OK, then update Identity server. 


Enabling reCAPTCHA in Login Page 


To enable reCAPTCHA in login page, see “Enabling reCAPTCHA in Login Page” on page 255. 


Configuring Authentication Methods 


Authentication methods let you associate authentication classes with user stores. You use a 
particular authentication class to obtain credentials about an entity, and then validate those 
credentials against a list of user stores. 


After the system locates the entity in a particular user store, no further checking occurs, even if the 
credentials fail to validate the entity. Typically, the entity being authenticated is a user, and the 
definition of an authentication method specifies whether this is the case. You can alter the behavior of 
an authentication class by specifying properties (name/value pairs) that override those of the 
authentication class. 
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To configure a method for an authentication class: 


1 Click Devices > Identity Servers > Edit > Local > Methods. 


2 To delete a method, select the method, then click Delete. 


A method cannot be deleted if a contract is using it. 


3 To modify an authentication method, click its name, or to create one, click New. 
4 Fill in the following fields: 


Display Name: The name to be used to refer to the new method. 


Class: The authentication class to use for this method. See Section 5.1.2, “Creating 
Authentication Classes,” on page 370. 


Identifies User: Specifies whether this authentication method must be used to identify the user. 
Usually, you must enable this option. When configuring multiple methods for a contract, you 
might need to disable this option for some methods. 


If you enable this option on two or more methods in a contract, these methods need to identify 
the same user in the same user store. 


If you enable this option on just one method in the contract, that method identifies the user when 
the authentication method succeeds. The other methods in the contract must succeed, but might 
not authenticate the user. For example, the method that identifies the user could require a name 
and a password for authentication, and the other method in the contract could prompt for a 
certificate that identifies the user’s computer. 


To achieve SSO on back end web application when the passwordfetch class is enabled, see TID. 


Overwrite Temporary User: If you select this check box, then the temporary user credentials 
profile got form previous authentication method in the same session will be overwritten with real 
user credentials profile got from this authentication method. 


Overwrite Real User: If you select this check box, then the real user credentials profile got form 
previous authentication method in the same session will be overwritten with real user credentials 
profile got from this authentication method. 


Add user stores to search. 


You can select from the list of all the user stores you have set up. If you have several user 
stores, the system searches through them based on the order specified here. If a user store is 
not moved to the User stores list, users in that user store cannot use this method for 
authentication. 


<Default User Store>: The default user store in your system. See Section 5.1.5, “Specifying 
Authentication Defaults,” on page 387. 


(Optional) Under Properties, click New, then fill in the following fields: 


Advanced Authentication Property: Select a property name from the list. For more 
information about each property, see “Optional Properties” on page 650. 


Property Name: The name of the property to be set. This value is case sensitive and specific to 
an authentication class. The same properties that can be set on an authentication class can be 
set on the method. 


You can use the method properties to override the property settings specified on the 
authentication class. For example, you might want to use the authentication class for multiple 
companies, but use a slightly different login page that is customized with the company’s logo. 
You can use the same authentication class, create a different method for each company, and use 
the JSP property to specify the appropriate login page for each company. 


For information about the available properties for the basic and form classes, see “Specifying 
Common Class Properties” on page 373 
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The Radius classes have the following additional properties that can be set on the method: 


+ RADIUS_LOOKUP_ATTR: Defines an LDAP attribute whose value is read and used as the 
ID is passed to the RADIUS server. If not specified, the user name entered is used. 


+ NAS_IP_ADDRESS: Specifies an IP address used as a RADIUS attribute. You might use 
this property for situations in which service providers are using a cluster of small network 
access servers (NASs). The value you enter is sent to the RADIUS server. 


If this method is part of a multi-factor authentication, you can set the following additional 
property: 


+ PRINCIPAL_MISMATCH_ERR: Specifies the error message to be displayed if this method 
identifies a different principal than other methods in the multi-factor authentication. 


Property Value: The values associated with the Property Name field. 
7 Click Finish. 
8 Continue with Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 
To use a method for authenticating a user, each method must have an associated contract. 


Configuring Authentication Contracts 


Authentication contracts define how authentication occurs. An Identity Server can have several 
authentication contracts available, such as name/password, X.509, or Kerberos. From the available 
contracts, you assign a contract to a specific resource or resources. It is access to a resource that 
triggers the authentication process. If the user has already supplied the required credentials for the 
contract, the user is not prompted for them again. 


Each contract is assigned a URI that uniquely identifies it. This URI can be shared with other 
providers so that they can identify the type of credentials the Identity Provider is requiring. You can 
also restrict a contract so that it can only be used for local authentication and not with other providers. 
1 Click Devices > Identity Servers > Edit > Local > Contracts. 
2 To delete a contract, select the contract, then click Delete. 
You cannot delete a contract if it is in use by an Access Gateway. 
3 To create a new contract, click New. 
4 Fill in the following fields: 
Display name: Specifies the name of the authentication contract. 


URI: Specifies a value that uniquely identifies the contract from all other contracts. It is used to 
identify this contract for external providers and is a unique path value that you create. No spaces 
can exist in the URI field. 


The following are all valid values for the URI: 


/mycompany/name/password/form 
http://mycompany.com/login 
secure/form/password/bcompany 


Password expiration servlet: Specifies a URL to a page where the user can change password 
when the password expires or is within the grace login period. You must use eDirectory to 
change the number of grace logins. Grace logins work only with eDirectory. 


For more information about how to use this type of servlet, see “Using a Password Expiration 
Service” on page 383. 
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Allow User Interaction: If you specify a password expiration servlet, you can enable this option, 
which allows the users to decide whether to go to the servlet and change their passwords or to 
skip the servlet. If you always want to force the users to go the servlet to change their 
passwords, do not enable this option. 


Login Redirect URL: You will be redirected to the URL specified in this field. Use this field for 
the following scenarios: 


+ Forcing the user to a specific home page after successful Access Manager authentication. 
+ Forcing the user to configure challenge/response forgotten password questions 


For more information about the URL parameters, see “Using Login Redirect URL Parameters” 
on page 386. 


Allow User Interaction: You can enable this option, which allows the user to decide whether to 
continue to access a pre-configured URL or to continue to the page that the user usually 
accesses. For example, the user may usually access www.a.com and have specified the redirect 
URL as https://someservice.com/path/ 

password?user=<USERID>&store=<STOREID>&r etur1l=<RETURN_URL> then, continue will allow 
you to continue with the website you access i.e. www.a.com and redirect URL will take you to the 
URL https://someservice.com/path/ 
password?user=<USERID>&store=<STOREID>&retur1l=<RETURN_URL>&action=expire and 
then to www.a.com. 


Authentication Level: A number you can assign to this authentication contract to specify its 
security level or rank. You use this setting to preserve authentication contracts of a higher 
security level. When you enable the Satisfiable by a contract of equal or higher level option on 
this page, the system uses this value as a reference. 


For example, you might create a name/password authentication contract and assign it to level 
one. You might also create an X.509 authentication contract and assign it to level two. If a user 
supplies the credentials for the X.509 level-two contract, the system does not require the 
credentials to satisfy the name/password level-one authentication contract. 


Authentication Timeout: Specify how long the session can be inactive before the user is 
prompted to log in again. The value can be from 5 minutes to 66535 minutes and must be 
divisible by 5. 


If you modify the timeout value for a contract, the newly assigned value is given to users as they 
log in. Currently logged in users retain the old value until they re-authenticate. 


You need to experiment to discover what values are best for your network configuration, your 
security requirements, and your users. 


+ Shorter timeouts increase back-channel traffic and require more threads for authentication 
checks, but quickly free resources that are being used by inactive users. If you have slow 
back-end services, users could get disconnected waiting for a response, and these 
disconnects can generate more authentication traffic. 


¢ Longer timeouts, which allow inactive users to remain connected, increase memory 
requirements to store session information, but require fewer threads and don't generate as 
much back-channel traffic. 


For example, if you set the timeout to 5 minutes, an authentication check needs to be done 12 
times each hour for each user authenticating with this contract. If the timeout is set to 60 
minutes, an authentication check is done only one time each hour for each user. However, for 
the 5 minute timeout, resources can be freed within 5 minutes of inactivity by the user. For the 
60-minute timeout, resources can take as long as 60 minutes to be freed, depending upon when 
the user goes inactive. 
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NOTE: In case of Name/Password - Basic and Secure Name/Password - Basic contracts 
applied to a protected resource, then you won't find the session as timed out, as the session gets 
renewed after timeout without user intervention using the Basic header sent from browser to 
Identity Provider. 


For information about how to use this feature with Access Gateway, see “Assigning a Timeout 
Per Protected Resource” on page 136. 


Activity Realm(s): Specify the name of the realm that can be used to indicate activity. Use a 
comma-separated list to specify multiple realms. This allows a user’s session to be kept alive 
when the user is accessing resources that are protected by different contracts. If both contracts 
belong to the same realm, activity on either resource keeps the session alive on the other 
resource. For more information about this feature, see “Using Activity Realms” on page 386. 


Satisfiable by a contract of equal or higher level: Allows the system to satisfy this 
authentication contract if a user has logged in using another contract of an equal or higher 
authentication level, as specified in the Authentication Level field of an authentication contract. 


When you enable this option, you need to be aware of the authentication levels you have set for 
other contracts and the level that has been assigned to the default contract. 


When the protected resource is configured with Name/Password -Form as Authentication 
procedure, the user authentication details are prompted with transient federation. This option 
must be enabled to avoid prompting for authentication in the Target Service Provider. 


Satisfiable by External Provider: Allows this contract to be selected when configuring an 
identity provider for Liberty or SAML 2.0. When you configure the authentication request, you 
can select a contract that has this option enabled and require the identity provider to use this 
contract for authentication to succeed. 


Requested By: Select one of the following options: 


+ Do not specify: Specifies that the identity provider can send any type of authentication to 
satisfy a service provider’s request, and instructs a service provider to not send a request 
for a specific authentication type or contract. 


+ Use Types: Specifies that authentication types must be used. 


Select the types from the Available types field to specify which type to use for 
authentication between trusted service providers and identity providers. Standard types 
include Name/Password, Secure Name/Password, X509, Token, and so on. 


+ Use Contracts: Specifies that authentication contracts must be used. 


Select the contract from the Available contracts list. For a contract to appear in the 
Available contracts list, the contract must have the Satisfiable by External Provider option 
enabled. To use the contract for federated authentication, the contract’s URI must be the 
same on the identity provider and the service provider. For information about contract 
options, see Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


Most third-party identity providers do not use contracts. 


Allowable Class: Specifies the class that instructs a service provider to send a request for a 
specific authentication type to the Identity Provider. You are allowed to modify this option only 
when you select authentication types. 


NOTE: In SAML 2.0 federation with Access Manager as a service provider, if external identity 
provider is authenticating a user, it sends <AuthnContext> information after authentication in the 
response. Access Manager uses this <AuthnContext> to find a matching contract at the service 
provider to identify the user. It identifies the contract by trying to match 
<saml:AuthnContextClassRef> with AllowableClass attribute or 
<saml:AuthnContextDeclRef> with URI attribute of existing contracts at the service provider. 
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For example, if the external identity provider sends the following AuthnContext: 


<saml:AuthnContext> 
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</ 
saml:AuthnContextClassRef> <saml:AuthnContextDeclRef>adroit : login: user :np</ 
saml:AuthnContextDeclRef> </saml:AuthnContext> 


and if Access Manager(as a Service Provider) has a contract A with uri = 
adroit :login:user:np or with Allowable class = 
urn:oasis:names:tc:SAML:2.0:ac:classes:Password, then it matches the contract. 


NOTE: The Allowable class field is blank when an inbuilt Authentication Class is used in Identity 
Server. 


Methods and Available Methods: Specifies the authentication method to use for the contract. 
You can specify the order in which the methods are executed for login; however, this is not a 
graded list, so all the methods you specify are required. Available methods are the 
authentication methods you have set up. 


You can enable the multi-factor authentication by associating more than one methods to a 
contract. 


If you add more than one X.509 method, only the first one is used and it is automatically moved 
to the top of the list. 


When you choose a secure method, such as Secure Name/Password, ensure that you have 
enabled security for Identity Server configuration by setting the protocol to HTTPS. See 
Chapter 17, “Enabling SSL Communication,” on page 977. 


5 Click Next. 
6 Configure a card for the contract by filling in the following: 


ID: (Optional) Specify an alphanumeric value that identifies the card. If you need to reference 
this card outside of Administration Console, you need to specify a value here. If you do not 
assign a value, Identity Server creates one for its internal use. 


Text: Specify the text that is displayed on the card to the user. 


Image: Specify the image to be displayed on the card. Select the image from the drop down list. 
To add an image to the list, click Select local image. 


Show Card: Determine whether the card is shown to the user, which allows the user to select 
and use the card for authentication. If this option is not selected, the card is only used when a 
service provider makes a request for the card. 


Passive Authentication Only: Select this option if you do not want Identity Server to prompt the 
user for credentials. If Identity Server can fulfill the authentication request without any user 
interaction, the authentication succeeds. Otherwise, it fails. 


7 Click Finish, then OK. 
8 Update Identity Server and any devices that use Identity Server configuration. 
9 To use this contract, you must configure Access Manager to use it: 


+ You can assign it as the default contract for Identity Server. See Section 5.1.5, “Specifying 
Authentication Defaults,” on page 387. 


+ You can configure a protected resource to use it. See Chapter 3.8, “Protecting Web 
Resources Through Access Gateway,” on page 118. 
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Configuring Options for an Authentication Contract 


You can configure an authentication contract to perform the following actions: 


¢ To redirect a user trying to log in to the authentication contract with an expired password to the 
password management URI. For more information about how and where to use this option, see 
“Redirection to Password Management Servlet Protected by Access Gateway When Password 
Expires” on page 385. 


¢ To hide contracts with equal levels. 
Perform the following steps: 


1 Click Identity Servers > Edit > Local > Contracts > [Contract Name]. 
2 Click Options > New. 
3 Specify the following details: 


Property Description 


AUTHENTICATE WITH EXPIRED PASSWORD Select the Property Value as true if you want to 
redirect a user logging with an expired password to 
the password management URI protected by an 
Access Gateway. 


HIDE CARDS WITH EQUAL LEVEL Select the Property Value as true if you want to 
disable showing any other higher level 
authentication cards, if Satisfiable by a contract of 
equal or higher level is enabled. 


OTHER Specify Property Name and Value if you want to 
configure any other property for this contract. 


4 Click OK. 


Using a Password Expiration Service 


Access Manager works with any password management service that works with your user store. For 
an implementation example, see Configuring Access Manager for UserApp and SAML. 


Configure the following options: 


+ “URL Parameters” on page 384 

¢ “Forcing Authentication after the Password Has Changed” on page 384 
¢ “Grace Logins” on page 385 

+ “Federated Accounts” on page 385 


¢ “Redirection to Password Management Servlet Protected by Access Gateway When Password 
Expires” on page 385 
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URL Parameters 


When you are defining the URL for the password service on the Contracts page, the following 
optional tags can be used in the parameter definitions of the URL. You need to use parameter names 
that are understood by the service you have selected to use. Identity Server does not need to 
understand these parameters, but the password expiration service needs to understand them. 


The table below lists a few common ones. Your service might or might not use these, and might 
require others. 


Parameter Description 
<USERID> Provides the DN of the user with a password that is expired or expiring. 
<STOREID> Provides the name of the user store that authenticated the user before redirecting 


the user to the password expiration service. 


<RETURN_URL> Provides the URL at Identity Server to which the user can be redirected after the 
password service completes. 


action=expire Causes the password expiration service to behave as though the user’s password 
policy is set to allow the user to reset the password even though the user’s policy 
might be set to show the user a hint. The user sees the page to create a new 
password rather than seeing a hint for an existing password. 


For example: 


https://someservice.com/path/password?user=<USERID>&s tore=<STOREID> 
&returl=<RETURN_URL>&action=expire 


NOTE: If you copy and paste this text, ensure that you remove the white space between <STOREID> 
and &returl. 


Identity Server fills in these values, which results in the following URL: 


https://someservice.com/path/password?user=joe.novell&store=userstore1& 
returl=https://myidp.com/nidp/idff/sso&action=expire 


Forcing Authentication after the Password Has Changed 


The password service can also include parameters on the return URL sent to Identity Server. Identity 
Server understands the following parameter: 


Parameter Description 


forceAuth=TRUE When the user is returned to Identity Server, this parameter forces the user to 
authenticate with the new password. This eliminates the possibility of an old 
password being used in an Identity Injection policy. 


The following example sends this parameter with https://testnidp.novell.com:8443 as the base 
URL of Identity Server. 


<form id="externalForm" action='https://testnidp.novell.com:8443/nidp/idff/ 
$so?sid=0&id=117&forceAuth=TRUE' method="post"> 


When the user is redirected to the password management service URL because of an expired 
password, the POST data in that redirect contains the sid=<> and id=<> values as part of the value 
used for Identity Server return URL. 
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Grace Logins 


If you specify a password service and do not specify a value for the number of grace logins in 
eDirectory, the contract redirects to the password management service only when the grace login 
count has reached 0 and the password has expired. 


Identity Server needs to read the value of the grace login attribute to properly redirect to the password 
management servlet. If restricting grace logins is not important to your security model, enable grace 
logins and set the maximum to 9999 (the equivalent of infinite in most environments). For more 
information, see TID 3465171 (http:/Awww.novell.com/support/php/ 
search.do?cmd=displayKC&docType=kc&externalld=34651 71 &sliceld=2&docTypelD=DT_TID_1_1 
&dialogID=131458644&stateld=0%200%20131454892). 


Federated Accounts 


A user’s password does not expire and grace logins are not decremented when you have the 
following setup: 

¢ Identity Server is configured to act as a service provider 

¢ User identification is configured to allow federation 

¢ Federation is set up with SAML 2.0, Liberty, or WS Federation protocols 
The password expiration service is not called because the user is not using a password for 
authentication. The service can only be called when the user’s account is defederated. After the user 


has defederated the account, the next time the user logs in, a password is required and the service is 
called. 


Redirection to Password Management Servlet Protected by Access Gateway 
When Password Expires 


When an Active Directory user with an expired password logs in to an authentication contract with a 
Password Expiration servlet configured, the user is redirected to the password management URI. If 
the Password Management portal is protected by Access Manager, the user is prompted again for 
authentication and is not permitted to login as the user password has expired. 


If you want the user to be redirected to the Password Management Servlet, perform the following 
steps: 
1 Click Devices > Identity Servers > Edit > Local > Methods. 


2 Select the authentication method, which is used by the contract where Password Management 
Servlet is configured. 


3 Add the following property for the method used by contract with Password Expiration servlet: 
Property Name = ExpiredCheck 
Property Value = true 

4 Go to Identity Servers > Edit > Local > Contracts. 

5 Click the associated contract and then click Options > New. 


6 Select AUTHENTICATE WITH EXPIRED PASSWORD in Property Type and true in Property 
Value. 


7 Click OK > Apply, and then Update Identity Server. 
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Using Login Redirect URL Parameters 


When you are defining the URL for login redirect URL on the Contracts page, the following optional 
tags can be used in the parameter definitions of the URL. You need to use parameter names that are 
understood by the service you have selected to use. The login redirect URL must understand the 
name-value pairs you have defined and will use the resolved values in the redirected URL. 


Parameter Description 
<USERID> Provides the DN of the user with a password that is expired or expiring. 
<STOREID> Provides the name of the user store that authenticated the user before redirecting 


the user to the password expiration service. 

<RETURN_URL> Provides the URL at Identity Server to which the user can be redirected after the 
password service completes. 

For example: 


https://someservice.com/path/password?user=<USERID>&store=<STOREID> 
&retur1l=<RETURN_URL> 


NOTE: If you copy and paste this text, ensure that you remove the white space between <STOREID> 
and &returl. 


Identity Server fills in these values, that results in the following URL: 


https://someservice.com/path/password?user=joe.novell&store=userstore1& 
returl=https://myidp.com/nidp/idff/sso 


In addition to the above three parameters you can also configure other parameters. 


Using Activity Realms 


Activity realms are designed to be used with an Access Manager system that uses multiple contracts 
to protect resources that require different activity timeouts. Activity realms allow you to define how 
activity at one protected resource affects the activity timeout at another protected resource. 


An activity realm essentially represents a time line that tracks the last activity for any resource that is 
protected by a contract assigned to the activity realm. When a protected resource is accessed, the 
activity realm associated with the contract is marked as having activity. The contract times out for a 
protected resource when the elapsed time for activity on the activity realm is greater than the time 
limit specified in the contract. 


For example, suppose you create an activity realm called shared1 and assign it to contract C1 with a 
timeout of 30 minutes and to contract C2 with a timeout of 15 minutes. Any activity at the resource 
protected by C1 or C2 marks activity to the shared1 time line. Figure 5-3 illustrates this scenario. 


Figure 5-3 Two Contracts Sharing an Activity Realm 
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In Figure 5-3, the user logs into PR1 at time 0, then logs into PR2 at time 6. During the next 30 
minutes, the user is active on PR1. The time line for the shared1 activity realm is updated with the 
user's activity. The user then access PR2 at time 38. Even though no activity has taken place on PR2 
for more than the 15-minute contract timeout, PR2 does not time out because activity has occurred 
within this time at PR1 and because the resources share the same activity realm. Assigning two or 
more contracts to the same activity realm allows the contracts to influence the timeouts of the other 
contracts in the activity realm. 


When you configure protected resources to use different contracts with different timeouts, they can 
keep each other alive when they share the same activity realm. If protected resources must not affect 
each other's activity, they must not share a common activity realm. 


You can assign a contract to multiple activity realms. With this configuration, activity on a resource 
updates the time lines of all activity realms associated with the contract. As long as one of the activity 
realms has activity within the contract’s timeout limit, the user’s session remains authenticated. 


Activity realms are defined by specifying a name, and the names are case insensitive. Use a comma- 
separated list to specify multiple names. The system has two default realms that you can use: 


+ Any: Leave the field blank or specify any when you want the user’s session to remain alive as 
long as there is some activity by the user at Access Gateway or at Identity Server. 


When Identity Server receives an assertion from another Identity Server that cannot be mapped 
to a contract, the activity realm is set to any with the timeout value equal to the value of the 
Tomcat session. (The Tomcat session timout is set to the greatest timeout value of the contracts 
configured for Identity Server.) 


+ NIDPActivity: Specify NIDPActivity for the realm when any activity at Identity Server by the 
user can be used to keep the user’s session alive. 


When you place multiple contracts in the same activity realm, you need to plan carefully so that 
security limits aren’t overruled by activity on less critical protected resources. You also need to 
carefully balance the desire for single sign-on with the need to require reauthentication for sensitive 
data. Highly sensitive resources are most secure when they are protected by a contract that is 
created from its own unique method and that is assigned its own unique activity realm. For more 
information, see “Assigning a Timeout Per Protected Resource” on page 136. 


Specifying Authentication Defaults 


You can specify default values for how the system processes user stores and authentication 
contracts. The default contract is executed when users access the system without a specified 
contract, and when Access Gateway is configured to use any authentication. 


Additional default contracts can be specified for well-known authentication types that might be 
required by a service provider. These contracts are executed when a request for a specific 
authentication type comes from a service provider. 


1 Click Devices > Identity Servers > Edit > Local > Defaults. 


2 Configure the following fields as necessary: 


User Store: Specifies the default user store for local authentication. If you selected <Default 
User Store> when configuring an authentication method, the system uses the user store you 
specify here. 


Authentication Contract: Specifies the default authentication contract to be used when users 
access Identity Server directly or a protected resource is configured to use Any Contract. If you 
create a new contract and specify it as the default, ensure that you update Access Gateway 
configuration if it has protected resources configured to use Any Contract. 
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Authentication Type: Specifies the default authentication contracts to be used for each 
authentication type. When a service provider requests a specific authentication type, rather than 
a contract, the identity provider uses the authentication contract specified here for the requested 
authentication type. For more information, see “Specifying Authentication Types” on page 388. 


3 Click OK. 
4 Update Identity Server. 


Specifying Authentication Types 


Trusted service providers can send Identity Server an authentication request that contains a request 
for contract or for an authentication type. When the request is for an authentication type, Identity 
Server must translate the type to a contract before authenticating the user. You can use the 
Authentication Type section of the Defaults page to specify which contract to use for the common 
types (classes). 


Identity Server has not implemented all possible types. For types that do not appear on the Defaults 
page, you can do one of the following: 


+ You can define a contract for the class whose URI matches the requested class type. When the 


authentication request is received, Identity Server uses the URI to match the request with a 
contract. 


When you create such a contract, you are stating that the contract is security equivalent to the 
class that is being requested. For configuration information, see “Creating a Contract for a 
Specific Authentication Type” on page 388. 


You can use the Trust Levels class to assign an authentication level for the requested class. This 
level is used to rank the requested type. Using the authentication level and the comparison 
context, Identity Server can determine whether any contracts meet the requirements of the 
request. If one or more contracts match the request, the user is presented with the appropriate 
authentication prompts. 


For configuration information, see “Configuring the Trust Levels Class” on page 180. 


Creating a Contract for a Specific Authentication Type 


The following steps explain how to create a contract that matches what a trusted service provider is 
asking for in its authentication request. 

1 Click Devices > Identity Servers > Edit > Local > Contracts. 

2 To create a new contract, click New. 

3 Fill in the following fields: 


Display name: Specifies the name of the authentication contract. 


URI: Specifies a value that uniquely identifies the contract from all other contracts. This value 
must match what the service provider is sending in its authentication request for the type. 


Authentication Level: (Optional) Specify a security level or rank for the contract. This value is 
not used when authentication request sets the comparison type to exact. It is only used when a 
contract is selected based on a comparison of authentication levels. 


If the service provider sets the comparison type to minimum, the authentication level can be the 
same or higher. If the comparison type is set to better, the authentication level must be higher. 


Methods: Select the method that matches the class or type you specified in the URI. 
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The other fields for the contract are not requirements of the authentication request and can be 
configured to meet the requirements of Identity Server. For information about these fields, see 
Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


4 Click Next. 
5 Configure an authentication card for the contract. 


For information about these fields, see Section 5.1.4, “Configuring Authentication Contracts,” on 
page 379. 


6 Click Finish, then OK. 
7 Update Identity Server. 


Persistent Authentication 


This authentication class stores user session on the browser after successful login. When the user is 
prompted for authentication subsequently, this class will reuse the saved authentication instead of 
prompting the user for credentials. The user will be prompted for credentials again only when the 
cookie lifetime expires. This authentication class is used only for applications that do not require very 
high security. You can configure persistent authentication as a standalone class. 


Frequent Re-authentication Using Password 


This class helps in configuring websites that have low security such as enterprise forums. Frequently 
typing the password to re-authenticate may be vulnerable and cause security issues. To avoid this 
with PersistentAuthClass configuration you will not be required to re-authenticate using the 
password frequently. For sites that you use a low-grade identity for example, enterprise forums or 
some web sites that restrain your preferences, having to re-authenticate every few-hours is annoying. 
Some web sites offer the remember my password feature that will not ask the user to re-authenticate 
if you select this option. This class provides that remember my password functionality so that the user 
does not need to frequently re-authenticate. 


PersistentAuthClass Properties 


You can set the following class properties in the configuration file. 


+ CryptoKey: This key is used to encrypt the user's information in the cookie. If this value is long 
and random, the user information will be secure. The value must be at least ten characters. The 
certificate private key will be used if you do not set this value. The certificate private key will be 
used if you do not set this value. If you change or update the certificate, the user is re- 
authenticated. 


¢ CookieSuffix: The Cookie Name is derived using this suffix. PA_ is added as a prefix to the 
cookie name. By default, cookie name is PALPERSISTENT_AUTH. For example, if you 
configure the CookieSuffix as PER_AUTH, Identity Server sends cookie with PALPER_AUTH 
name at browser. 


+ MaxAgeSeconds: This property will decide the cookie lifetime. Default value is 86400 seconds 
(1 day). Maximum value is 4294967295 seconds. 


+ ParamName: The name of the HTTP parameter to enable this feature. The default value of the 
parameter is EnableCookieAuth. If you want to modify the default value of parameter name for 
example to TestCookieName, follow the procedure given below. 


1. Login to Identity Server. 
2. Go to /opt/novell/nids/1lib/webapp/jsp 
3. Open login. jsp file using an editor. 
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4. Search for EnableCookieAuth parameter name and provide the new name as 
TestCookieName in the input tag. 


5. Ensure that you select the Remember Me option. 
6. Restart Identity Server. 


This value is used by Identity Server to identify if user has enabled Remember Me option on 
the login page. 


Customizing Login Page For Persistent Authentication 


To enable Remember Me option on a custom login page, use the following custom code: 


<td align=left> 

<input type="checkbox" name="EnableCookieAuth" value="true" /> <label> Remember Me 
</label> 

</td> 

</tr> 

<tr></tr> 

<tr> <td> <span class="instructions">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; (Do 
not check this box if you are using public computer. )</span> </td></tr> 


NOTE: 


+ Ensure that you add the MainJSP and JSP in the method property. 


¢ This class doesn't replace the form-based contract. For more information, see “Customizing 
Identity Server Login Page” on page 256. 


Configuring Persistent Authenticator Class 


The following procedure allows you to configure the PersistentAuthClass. Persistent Authentication 
supports method properties described in the following section. 
1 Login to Administration Console. 
Click Devices > Identity Servers > Edit > Local > Classes. 
Click New, then specify a Display name for example, PersistentAuth. 
Select PersistentAuthClass from the Java Class drop-down list. 
Click New to create a new authentication class. 
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In the Add property window, specify the following values. Specifying these values are optional. 


+ Property Name: Specify the name of the property. For more information on the names you 
can specify here, see “PersistentAuthClass Properties” on page 389 


+ Property Value: Specify the property value you would like to define here. 
7 Click OK and Finish. 
8 Continue with creating a contract and method for this class. 


For configuration information, see Section 5.1.3, “Configuring Authentication Methods,” on 
page 377 and Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 
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Logging Out of the Persistent Sessions 


When a user performs an explicit logout, Identity Server clears the persistent authentication cookie at 
browser if the logout request goes through the browser. If SOAP communication is used between the 
service provider and Identity Server, then Identity Server does not clear the cookie automatically. The 
cookie can only be cleared by sending a request to a page on the server that issued it. If the page is 
available on Identity Server, the clearCookieAuth. jsp file clears the page. You must customize the 
service provider's logout page to run Identity Server's clearCookieAuth. jsp page. 


The clearCookieAuth. jsp file clears it. The URL for this page will be https://idpserver.example.com/ 
nidp/clearCookieAuth.jsp. Any request to that URL will clear the authentication cookie. 


With this class in use, the user will be unable to logout of the system because re-accessing any 
protected page will simply re-authenticate the user using the user information stored in the browser 
stored. There are at least two ways to invalidate an outstanding browser stored authentication cookie. 
The first is to change the user’s password and second is to clear the stored cookie from the browser. 
Only way to invalidate the cookie is to change the encryption key used. The cookie that is created can 
only be cleared by a request from the server which created it. 


The following configurations are specific to the Novell service provider. If the users uses third party 
service provider, then the user must customize the logout pages. 


In a federation scenario add the following to the logoutSuccess. jsp file at /opt/novell/nam/idp/ 
webapps/nidp/jsp/ of the service provider. You can have logout page redirect to this page, or have 
an <iframe> that references the page. You may also customize the /opt/novell/nam/mag/webapps/ 
nesp/jsplogoutSuccess. jsp file to provide login links or instructions to your user. 


<tr> 

<td> <iframe src="https://idp.labs.com:8443/nidp/jsp/clearCookieAuth. jsp" 
width="0" height="0"> </td> 
</tr> 


where idp.labs.com is the URL of Identity Server. 


Limitations 


Following are the limitations with the Persistent Authentication Class: 


+ User is authenticated even if the password is changed. 


+ If the user is already logged in with Remember Me option enabled, you will be unable to stop the 
session until the cookie expires. 


Client Integrity Check 


You can configure a client integrity check policy to verify the recommended software (such as firewall 
and antivirus software) are installed on the client machine. You can configure different policies for 
Windows, Linux, and Macintosh machines and specify software that must be available in client 
machines to pass the client integrity check. 


You need to create an identity provider authentication class that checks for the specified software on 
the client machine. You can configure policies to check processes, files, Windows registry, system 
services, and so on. This class can be executed with the first method of the contract. If the check 
fails, the user authentication fails. 
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Configuring Client Integrity Check 


1 Download the Client Integrity Check (CIC) package from the CIC Package download page 


(https://www.netig.com/documentation/access-manager-43/resources/CICtool_utility.tar.gz) and 
extract the CIC_utility.tar.gz file. 


Specifying details for the Operating System 
Traverse to CICtool/conf/config. xml file. Add the following details to the config. xml file: 


<OperatingSystem Name="Linux" UserInterfaceID="Linux" CICOSID="Linux"> . . . </ 
OperatingSystem> 


To define operating system details for Windows and Macintosh, substitute UserInterfaceID, 
Name and CICOSID with Macintosh or Windows. 


NOTE: The attribute Name indicates the identifier for the operating system. Ensure that you use 
the same identifier for UserInterfaceID and CICOSID. 


Adding a Category 


A category is a group of similar software. For example, a firewall category can contain a list of 
firewalls such as the Windows Firewall and ZoneAlarm firewall. You can configure multiple 
software categories under each operating system in single cic policy. 


When multiple categories are configured for an operating system, if one of the enabled category 
does not exist on the client, the client integrity check fails. 


A category can be added to a operating system by adding <Type> tag in config. xml as follows: 


<OperatingSystem Name="Linux" UserInterfaceID="Linux" CICOSID="Linux"> <Type 
Name="Firewall_Linux" UserInterfaceID="Firewall_Linux" Status="true" 
CICTypeID="Firewall_Linux"> ... </Type> <Type Name="Antivirus_Linux" 
UserInterfaceID="Antivirus_Linux" Status="true" CICTypeID="Antivirus_Linux"> . 
</Type></OperatingSystem> 


As described in this example, multiple categories can be configured under an operating 
system.The Name attribute inside the <Type> tags indicate the category name. 


Set status to true to enable a specific category. 
Adding Applications for a Category 


A category consists of group of applications. You can add more than one application under a 
category. A client workstation is checked for the presence of any one of the software items in the 
category. If at least one of the enabled application definition exists on the system, the client 
integrity check passes for that category. 


To configure applications to a category, add <Info> tag as shown below. 


<OperatingSystem Name="Linux" UserInterfaceID="Linux" CICOSID="Linux"> <Type 
Name="Firewall_Linux" UserInterfaceID="Firewall_Linux" Status="true" 
CICTypeID="Firewall_Linux"> <Info Name="FireStarter" 
UserInterfaceID="FireStarter" Status="true"> . . . </Info> </Type> <Type 
Name="Antivirus_Linux" UserInterfaceID="Antivirus_Linux" Status="true" 
CICTypeID="Antivirus_Linux"> <Info Name="AntiVir" UserInterfaceID="Antivir" 
Status="true"> . . . </Info> </Type></OperatingSystem> 


The Name attribute inside the <Info> tags indicate the application name. Set status to true to 
enable a specific application. 


NOTE: To enable an application you must have already enabled the category that it belongs to. 


Adding Attributes for an Application 


392 Configuring Authentication 


After you have added an application to a category, you must configure the attributes for each of 
these applications. These attributes can be in the form of RPMs, processes, registry keys, or 
executable files. The client integrity check detects the presence of these attributes. 


These attributes can be configured under each application by adding attribute type tags to 
config.xml as follows: 


<OperatingSystem Name="Linux" UserInterfaceID="Linux" CICOSID="Linux"> <Type 
Name="Firewall_Linux" UserInterfaceID="Firewall_Linux" Status="true" 
CICTypeID="Firewall_Linux"> <Info Name="FireStarter" 
UserInterfaceID="FireStarter" Status="true"> <AbsoluteFile UserInterfaceID="0" 
Name="/var/lock/subsys/firestarter" HashMD5="""/> <RPM UserInterfaceID="1" 
Name="FireStarter" Version="0.9.3" /> </Info> </Type> <Type 
Name="Antivirus_Linux" UserInterfaceID="Antivirus_Linux" Status="true" 
CICTypeID="Antivirus_Linux"> <Info Name="AntiVir" UserInterfaceID="Antivir" 
Status="true"> <Process UserInterfaceID="0" Name="antivir" Owner="root" /> 
<AbsoluteFile UserInterfaceID="1" Name="/usr/lib/AntiVir/avguard" HashMD5="ss" 
/> </Info> </Type> </OperatingSystem> 


In this example, <AbsoluteFile>,<RPM>,<Process>,<AbsoluteFile> are examples of attribute 
type tags and fields like Name, Version,Owner are examples of attribute names. 


For more information about attributes for applications on different operating systems, see 
“Configuring Attributes for an Application” on page 396 


Client Security Levels 


You can configure different levels of client security. For more information about the different 
levels of client security, see “Client Security Levels” on page 395 


The security level can be configured by adding the following details to the config. xml file: 


<SecurityLevel Name="None" UserInterfaceID="None" DisplayMessage="Client 
Integrity failed" SecurityLevelID="None" CICReferenceCount="0" 
TrafficReferenceCount="1" /><SecurityLevel Name="Low" UserInterfaceID="Low" 
DisplayMessage="Your workstation is at Least Secure Level" SecurityLevelID="1" 
CICReferenceCount="3" TrafficReferenceCount="1"> . . .</SecurityLevel> 


The value of the Name field can be None,Low,Moderate and High,and the SecurityLevelID 
value in each case must be None,1,2 and 3 respectively. 


Adding Operating System details to the Security Level 


Under each security level, an operating system can be configured by adding <CICOS> tag as 
follows: 


<SecurityLevel Name="Low" UserInterfaceID="Low" DisplayMessage="Your 
workstation is at Least Secure Level" SecurityLevelID="1" CICReferenceCount="3" 
TrafficReferenceCount="1"> <CICOS UserInterfaceID="Linux" CICOSIDRef="Linux"> 
. </CICOS> <CICOS UserInterfaceID="Windows" CICOSIDRef="Windows"> . </CICOS> 
<CICOS UserInterfaceID="Macintosh" CICOSIDRef="Macintosh"> . . . </CICOS></ 
SecurityLevel> 


This example shows configuration of operating system for security level Low,Other levels can be 
incorporated in the same manner. 


Under each operating system, category can be configured by adding <CICType> tag as follows: 


<SecurityLevel Name="Low" UserInterfaceID="Low" DisplayMessage="Your 
workstation is at Least Secure Level" SecurityLevelID="1" CICReferenceCount="3" 
TrafficReferenceCount="1"> <CICOS UserInterfaceID="Linux" CICOSIDRef="Linux"> 
<CICType UserInterfaceID="Firewall_Linux" CICTypeIDRef="Firewall_Linux" 
CICTypeStatus="true" /> <CICType UserInterfaceID="Antivirus_Linux" 
CICTypeIDRef="Antivirus_Linux" CICTypeStatus="true" /> </CICOS> <CICOS 
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UserInterfaceID="Windows" CICOSIDRef="Windows"> <CICType 
UserInterfaceID="Firewall_ Windows" CICTypeIDRef="Firewall_Windows" 
CICTypeStatus="true" /> <CICType UserInterfaceID="Antivirus_Windows" 
CICTypeIDRef="Antivirus_Windows" CICTypeStatus="true" /> </CICOS> <CICOS 
UserInterfaceID="Macintosh" CICOSIDRef="Macintosh"> <CICType 
UserInterfaceID="Antivirus_Mac" CICTypeIDRef="Antivirus_Mac" 
CICTypeStatus="true" /> </CICOS></SecurityLevel> 


Traverse to the CIC/CICtool/bin directory. Execute the CICtool binary by using the following 
command: 


$./CICtool ../conf/config. xml. 

This creates .txt policy files in the CICtext folder. 

In Identity Server, create the following directories by using the following commands: 
For Linux: $mkdir /opt/novell/nam/idp/webapps/nidp/classUtils/linux 

For Macintosh: $mkdir /opt/novell/nam/idp/webapps/nidp/classUtils/mac 
For Windows: $mkdir /opt/novell/nam/idp/webapps/nidp/classUtils/windows 


From the CICtext directory, copy the cic_linux.txt, cic_mac.txt and cic_windows.txt to 
the respective CIC system directory created in step 10. 


Use the following command to copy: 


For Linux: $ scp cic_linux.txt <idp login credentials>:/opt/novell/nam/idp/ 
webapps/nidp/classUtils/linux 


For Macintosh: $ scp cic_mac.txt <idp login credentials>:/opt/novell/nam/idp/ 
webapps/nidp/classUtils/mac 


For Windows: $ scp cic_windows.txt <idp login credentials>:/opt/novell/nam/idp/ 
webapps/nidp/classUtils/windows 


Substitute idp login credentials with the server /Paddress, port, username and password to login 
to Identity Server. 


From the CIC bin directory, copy the LinCic, MacCic and wincic.exe to the respective CIC 
system directory created in step 10. 


Use the following commands to copy: 


For Linux: $ scp LinCic <idp login credentials>:/opt/novell/nam/idp/webapps/ 
nidp/classUtils/linux 


For Macintosh: $ scp MacCic <idp login credentials>:/opt/novell/nam/idp/webapps/ 
nidp/classUtils/mac 


For Windows: $ scp wincic.exe <idp login credentials>:/opt/novell/nam/idp/ 
webapps/nidp/classUtils/windows 


Substitute idp login credentials with the server IPaddress, port, username and password to login 
to Identity Server 


Click Identity Server > Edit > Local > Classes > New 


14 Specify a name for the class and select ClientIntegrityCheckClass in Java class. Click Next. 


15 Click New and specify the following property name and property value: 


Name Value 
windowsBinary /nidp/classUtils/windows/wincic.exe 
windowsPolicy /nidp/classUtils/windows/cic_windows.txt 
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Name Value 


linuxBinary /nidp/classUtils/linux/LinCic 
linuxPolicy /nidp/classUtils/linux/cic_linux.txt 
maci386Binary /nidp/classUtils/mac/MacCic 
maci386Policy /nidp/classUtils/mac/cic_mac.txt 


16 Click OK > Finish. 


17 


Create a method for this class and deselect Identifies User check box and set all other fields to 
default settings and click OK. For instructions, see Section 5.1.3, “Configuring Authentication 
Methods,” on page 377. 


18 Go to the Contracts tab and select CIC method from the Available Methods list and click OK. For 


instructions, see Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


Client Security Levels 


You can configure the level of security configured at the client machine. You can decide the 
categories of software that you want to be present for each level. 


You can configure the following security levels: 


+ 


Least Secure: Specifies the minimum categories of software that must be present on a client 
machine for the client to be at the lowest secure level. When a client is at a least secure level, 
you can configure the traffic policies so that the client has access to limited set of resources. 


Moderately Secure: Specifies the categories of software that must be present on a client 
machine for the client to be at a moderately secure level. When a client is at a moderately secure 
level, you can configure the traffic policies accordingly. 


Secure: Specifies the software categories that must be present on a client machine for the 
client to be secure. When a client is at a secure, the traffic policies can be configured so that the 
client has access to all or most of the protected resources, depending on the role of the client. 


None: If a client does not have any of the software such as firewall or antivirus specified in the 
client integrity check policy, then the security level of that client is None. When a client is at this 
level, the SSL VPN connection is established, but the client is given access to only a minimal set 
of resources. 
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5.1.7.3 Configuring Attributes for an Application 


Specify details for the attributes. The following table lists the attributes for applications on different 
operating systems: 


Operating 
System 


Linux 


Attribute Attribute Name 

Type 

RPM Name: Specify the name of the RPM that must be present on the client 
machine. 
Version: Specify the version of the RPM that must be present on the client 
machine. 

Process Name: Specify the name of the process that must be present on the client 
machine. 
Owner: Specify the owner of the process. 

Absolute File | Name: Specify the name and absolute path of the file that must be present on 
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the client machine. 


HashMD5: Specify the MD5 checksum value of the absolute file. To calculate 
the MD5 checksum value of an absolute file located in your local system, click 
Select File to select the file. The MD5 checksum value of the selected file is 
displayed. 


To calculate the MD5 checksum value for an absolute file that is on another 
system, remotely connect to that system, calculate the MD5 value, then copy 
the value in the HasMD5 field. 


NOTE: You can also copy the file from the remote system to the local system, 
then calculate the MD5 checksum by using the Select File option. However, 
this might change the MD65 value of the file during the process. If you want to 
use this method, then ensure that the file size and file contents did not change 
during the process. 


Operating | Attribute Attribute Name 


System Type 
Macintosh Package Name: Specify the name of the software package that must be present on the 
client machine. 
Version Specify the version of the software package. 
Process Name: Specify the name of the executable file that must be present on the 


client machine. 


Owner: Specify the owner of the process. 


Absolute File | Name: Specify the name and absolute path of the file that must be present on 
the client machine. 


HashMDS: Specify the MD5 checksum value of the absolute file. To calculate 
the MD5 checksum value of an absolute file located in your local system, click 
Select File to select the file. The MD5 checksum value of the selected file is 
displayed. 


To calculate the MD5 checksum value for an absolute file that is on another 
system, remotely connect to that system, calculate the MD5 value, then copy 
the value in the HasMD5 field. 


NOTE: You can also copy the file from the remote system to the local system, 
then calculate the MD5 checksum by using the Select File option. However, 
this might change the MD5 value of the file during the process. If you want to 
use this method, then ensure that the file size and file contents did not change 
during the process. 


Windows Process Name: Specify the name of the executable file that must be present on the 
client machine. 


RegistryKeyName: Specify the registry key name. When you add this name, 
make sure that you also specify a value for RegistryKey Value. 


ValueName: Specifies the value for RegistryKey configured. The data found in 
this key value must be the absolute path of the folder where the process file is 
present. 


Version: Specify the version of the software process that must be running in 
the client machine. 


NOTE: The version attribute specifies the Windows Explorer file version 
number. 
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Operating | Attribute 
System Type 


RegistryKey 


Attribute Name 


Name: Specify the name and absolute path of the registry key that must be 
present on the client machine. 


Value Name: Specify the name of the registry key value. 


Value Data: Specify a data for the registry key value. This data can be for 
registry type REG_BINARY, REG_DWORD, 
REG_DWORD_LITTLE_ENDIAN, REG_MULTI_SZ, or REG_SZ. The value 
for REG_DWORD and REG_DWORD_LITTLE_ENDIAN is hexadecimal or 
decimal. The value of a REG_MULTI_SZ or REG_SZ can be a string value or, 
numeric or alphanumeric. The value of REG_BINARY can be binary or 
hexadecimal. 


The Value name and Value data are separated by a comparison operator such 
as=, >. <, <=, >=. You must always use = with a string or with the 
registry type REG_BINARY. You can use any comparison operator with other 


registry types 


For example, if the registry key name is specified as RegKey with a Value 
Name of RegValue, a comparison operator of =, and a Value Data of 
RegData, the client integrity check process looks for the presence of RegKey 
with a value name RegValue = value data RegData on the client machine. If 
the registry is present with the specified values, the client passes the client 
integrity check. 


NOTE: Registry keys are not case sensitive, and they can contain either a 
single backslash (\) or double backslash (\\). 


For example: One of the registry key descriptions is 
HKEY_Local_Machine\\Software\\Symantec. It can also be written as 
HKEY_Local_Machine\Software\Symantec. 


Absolute File 


Name: Specify the name and absolute path of the file that must be present on 
the client machine. 


Version: Specify the version of the absolute file that must be running on the 
client machine. 


HashMD5: Specify the MD5 checksum value of the absolute file. To calculate 
the MD5 checksum value of an absolute file located in your local system, click 
Select File to select the file. The MD5 checksum value of the selected file is 
displayed. 


To calculate the MD5 checksum value for an absolute file that is on another 
system, remotely connect to that system, calculate the MD5 value, then copy 
the value in the HasMD5 field. 


NOTE: You can also copy the file from the remote system to the local system, 
then calculate the MD5 checksum by using the Select File option. However, 
this might change the MD5 value of the file during the process. If you want to 
use this method, then ensure that the file size and file contents did not change 
during the process. 


Service 
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Name: Specify the display name of the service. 


Status: Specify the status of the process in the client machine. The status of 
the process can be Running or Stopped. 


5.1.8 


Mutual SSL (X.509) Authentication 


Mutual authentication is used when a user is issued an X.509 certificate from a trusted source, and 
the certificate is then used to identify the user. To ensure the validity of the certificates, Access 
Manager supports both Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol 
(OCSP) methods of verification. 


To configure X.509 authentication, you need to create an authentication class, then configure the 
validation and attribute mapping options. 
1 Log in to Administration Console. 


2 Import the trusted root certificate or certificate chain of the Certificate authority into Identity 
Server trusted root store. 


For information about how to import trusted roots, see “Importing Public Key Certificates 
(Trusted Roots)” on page 971. 


Identity Server must trust the Certificate authority that created the user certificates. 


3 To create the X.509 authentication class, click Devices > Identity Servers > Edit > Local > 
Classes. 


Click New. 

Specify a display name, then select X509Class from the drop-down menu. 
Click Next. 

Configure the validation options: 


N © of ff 


Validations: The validation type. Trust validation occurs if the certificate chain is verified in the 
NIDP Trust Store. In addition to usual certificate validations, Identity Server supports CRL 
(certificate revocation list) and OCSP (Online Certificate Status Protocol) validations for each 
authentication request. 


Access Manager caches CRLs, so the revoked status of a newly revoked certificate is not picked 
up until the next cache refresh. For higher security requirements, use OCSP validation with CRL 
validation. You can select None, CRL, OCSP, OCSP-CRL, or CRL-OCSP validation. Ina 
production environment, for highest security, select either OCSP-CRL or CRL-OCSP validation. 
The default setting is to check OCSP first, then CRL. 


CRL Validation: Checks the CRL. If you enable CRL validations, the CRL distribution point 
extension is read out of the user’s X.509 certificate. The CRL distribution point contains the URL 
where the complete CRL can be found, as published by the certificate authority. The system 
checks the CRL itself and then checks to see if the user certificate is in the revoked list. The 
system can get the CRL over HTTP and LDAP. If you are not expecting the distribution point in 
user certificates, you can specify a value in the LDAP URL option to get the CRL. 


Access Manager supports two schemes for a URL: http:// and ldap: //. 


OCSP Validation: If OCSP validation is enabled, the Authority Info Access point (AIA) is read 
out of the user certificate, which contains the URL for the OCSP responder. A signed OCSP 
request for the user certificate is sent to OCSP responder. A signed OCSP response is received 
from the responder that has the revoked status for the user certificate. Alternately, if you are not 
expecting an AIA in a user certificate, you can specify a value in the OCSP responder URL field. 
The value you enter here overrides any OCSP responder URLs in a certificate. 


Access Manager supports two schemes for a URL: http:// and ldap: //. 


Disable Root CA Revocation Check: Disables whether to check if a certificate authority has 
been revoked. This option checks the CRL and OCSP for the trusted root certificate in the chain. 
You can enable or disable this option for X.509 user authentication performance. 
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If you enable the root CA revocation check, what Identity Server checks depends upon the 
certificates that have been added to Identity Server trust store. If the root certificate and the 
intermediate certificates in the chain are in the trust store, Identity Server only validates the client 
(leaf) certificate. If the trust store only contains the root certificate, the browser sends the 
intermediate and leaf certificates, which are then validated by Identity Server. 


Configure the trust stores: 


NIDP Trust Store: This trust store must contain the trusted root certificate of the certificate 
authorities that signed your user certificates. Click this link to add certificates to the trust store. 


OCSP Trust Store: This trust store must contain the signing certificate of the OCSP servers you 
want to trust. Click this link to add certificates to the trust store. You must add the signing 
certificate, not the trusted root certificate, for this feature to work. 


Configure the browser restart option. 


Some browsers, such as Internet Explorer, keep the SSL session active until the user closes the 
browser. When the user logs in with the certificate on a smart card, then removes the card and 
logs out but does not close the browser, the SSL session is still active. If another user has 
access to the machine, that user can use the existing session. 


To prevent this from happening, select Force browser restart on logout. 
Click Next. 
Continue with “Configuring Attribute Mappings” on page 400. 


Configuring Attribute Mappings 


The attribute mapping options allow you to specify how Identity Server maps the certificate to a user 
in the user store. Subject name is the default map. 


Step 3 of the wizard or click Devices > Identity Servers > Edit > Local > Classes > [Name of 
X.509 class] > Properties > Attributes. 


Configure attribute mappings. 


Show certificate errors: Displays an error page when a certificate error occurs. This option is 
disabled by default. 


Auto Provision X509: Enables using X.509 authentication for automatic provisioning of users. 

This option allows you to activate X.509 for increased security, while using a less secure way of 
authentication, such as username/password. Extra security measures can even include manual 
intervention to activate X.509 authentication by adding an extra attribute that is checked during 

authentication. 


An example of using this option is when a user authenticates with an X.509 certificate, a lookup 
is performed for a matching SASallowableSubjectNames with the name of the user certificate. 
When no match is found, and Auto Provision X509 is enabled, the user is presented with a 
custom error page specifying to click a button to provide additional credentials, such as a 
username and password, or to start an optional Identity Manager workflow. If the authentication 
is successful, then the user’s SASallowableSubjectNames attribute is filled in with the certificate 
name of the user certificate. 


When Auto Provision X509 is enabled, and the attribute that is used for subject name mapping 
is changed from the default sasAllowableSubjectNames, you need to ensure that the LDAP 
attribute that is used can store string values with a length as long as the longest client certificate 
subject name. For example, if you use the LDAP attribute title (which has an upper bound of 64 
characters) the Auto Provision X509 fails the provisioning part of the authentication if the client 
certificate subject name is longer 64 characters. The authentication works if a valid name and 
password is given. However, provisioning fails. 
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Attributes: The list of attributes currently used for matching. If multiple attributes are specified, 
the evaluation of these attributes must resolve to only one user in the user store. 


The evaluation first does a DN lookup for subject name or directory name mapping. If this fails, 
the rest of the mappings are looked up in a single LDAP query. 


Available attributes: The available X.509 attributes. To use an attribute, select it and move it to 
the Attributes list. When the attribute is moved to the Attributes list, you can modify the mapping 
name in the Attribute Mappings section. The mapped name must match an attribute in your 
LDAP user store. 


Directory name: Searches for the directory address in the client certificate and tries to match it 
to the DN of a user in the user store. If that fails, it searches the sasAllowableSubjectNames 
attribute of all users for a value that matches. The sasAllowableSubjectNames attribute must 
contain values that are comma-delimited, with a space after the comma. (For example, 
O=CURLY, OU=Organization CA or OQU=Organization CA, O=CURLY.) 


Email: Searches for the email attribute in the client certificate and tries to match it with a value in 
the LDAP mail attribute. 


Serial number and issuer name: Lets you match a user's certificate by using the serial number 
and issuer name. The issuer name and the serial number must be put into the same LDAP 
attribute of the user, and the name of this attribute must be listed in the Attribute Mappings 
section. 


When using a Case Ignore String attribute, both the issuer name and the serial number must be 
in the same attribute separated by a dollar sign ($) character. The issuer name must precede the 
$ character, with the serial number following the $ character. Do not use any spaces preceding 
or following the $ character. For example: O=CURLY, OU=Organization CA$21C0562C5C4 


The issuer name can be from root to leaf or from leaf to root. The issuer name must be comma- 
delimited with a space after the comma. (For example, O=CURLY, OU=Organization CA or 
OU=Organization CA, O=CURLY.) 


The serial number cannot begin with a zero (0) or with a hexadecimal notation (0x). If the serial 
number is OxOBACO5, the value of the serial number in the attribute must be BACOS5. The 
certificate number is displayed in Internet Explorer with a space after every fourth digit. However, 
you must enter the certificate number without using spaces. 


The LDAP attribute can be any Case Ignore List or Case Ignore String attribute of the user. If you 
are configuring your own attribute, ensure that the attribute is added to the Person class. When 
using a Case Ignore List attribute, both the issuer name and the serial number must be in the 
same list. The issuer name needs to be the first item in the list, with the serial number being the 
second and last item in the list. 


Subject name: Searches for the Subject name of the client certificate and tries to match it to the 
DN of a user in the user store. If that fails, it searches the sasAllowableSubjectNames attribute of 
all users for a value that matches the Subject name of the client certificate. The 
sasAllowableSubjectNames attribute must contain values that are comma-delimited, with a 
space after the comma. (For example, O=CURLY, OU=Organization CA or OU=Organization 
CA, O=CURLY.) 


Click Finish. 


4 Create a method for this class. 


For instructions, see Section 5.1.3, “Configuring Authentication Methods,” on page 377. 
Create a contract for the method: 
For instructions, see Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 
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If you want the user’s credentials available for Identity Injection policies, add the password fetch 
method as a second method to the contract. For more information about this class and method, 
see Section 5.1.11, “Password Retrieval,” on page 406. 


6 Update Identity Server. 


Setting Up Mutual SSL Authentication 


SSL provides the following security services from the client to the server: 


+ Authentication and nonrepudiation of the server, using digital signatures 
¢ Data confidentiality through the use of encryption 
¢ Data integrity through the use of authentication codes 


Mutual SSL provides the same things from the server to the client as SSL. It provides authentication 
and nonrepudiation of the client, using digital signatures. 


1 Set up Access Manager certificates for security, and import them into the Access Manager 
system. (See Section 13, “Creating Certificates,” on page 947.) 


2 Create an X.509 authentication class. (See Section 5.1.8, “Mutual SSL (X.509) Authentication,” 
on page 399.) 


3 Create an authentication method using this class. (See Section 5.1.3, “Configuring 
Authentication Methods,” on page 377.) 


4 Create an authentication contract using the X.509 method. (See Section 5.1.4, “Configuring 
Authentication Contracts,” on page 379.) 


5 Update Identity Server cluster configuration. (See “Updating an Identity Server Configuration” on 
page 253.) 


6 Update any associated Access Gateways to read the new authentication contract. 
7 Assign the contract to protect resources. 

See Section 3.8.4, “Configuring Protected Resources,” on page 128. 
8 Update Access Gateway. 


Customizing Certificate Errors 


In case of certificate validation failure, the browser displays a standard Page expired error. If you 
want Identity Server to display an Access Manager error instead of the usual error messages 
provided by the browser, edit the /opt/novell/nam/idp/conf/server . xml by using the following 
procedure: 


1 Search for the clientauth attribute in the server.xml file. 
2 Modify the value of the clientauth attribute from the default value of false to want. 


NOTE: if you use cliantauth=want in a connector, ensure that the connector also contains 
protocol="org.apache.coyote.httpi1.Http11Protocol". 


3 Save the file and restart Identity Server by using the rcnovell-idp restart command. 


This setting ensures that the certificate is exchanged between the client and the server. This will 
result in a prompt being displayed on the browser during authentication. 
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4 Export the user and server certificate from Administration Console by using the Security > 
Certificates option. 


To avoid the untrusted certificate messages in browsers, import the trusted root certificate of the 
CA into your browsers. For details, see Section 30.5.2, “Resolving Certificate Import Issues,” on 
page 1222. 


Configuring X.509 Authentication to Provide Access Manager Error 
Message 
You can configure the X.509 class property and Identity Server to avoid the browser provided 


message and display Access Manager error message. This occurs when the SSL mutual handshake 
fails because of non availability of client certificate. 


NOTE: You can specify the Port and URL name as per your environment. The URL name and port 
number specified in the following procedure is an example. 


Prerequisite: To configure you must have a parent domain, for example, https:// 
240onbox.provo.novell.com:8443/nidp/ and sub domain https://onbox.provo.novell.com:8448/ 
available. You can also have a different port or IP combination. 


Follow the procedure given below to configure X.509 based authentication for Access Manager 
specific error. 

Go to identity provider and navigate to /opt/novell/nam/idp/conf directory. 

Open server . xml file using the vi editor. 

Search for <Connector NIDP_Name="connector" and create a copy of existing connector. 


Bh WN RF 


Go to the new connector you created and search for clientAuth=false string andchange it to 
clientAuth=want. Change the port to a new port for example, 8448. 


5 Save the server.xml file and exit. 
6 Navigate to /opt/novell/nids/lib/webapp/META-INF/ directory and open context. xml file. 


7 Change Tomcat context.xml to set a same cookie for sub domains. Ensure that the path is set 
to "/" as follows. 


<?xml version="1.0" encoding="UTF-8"?> <Context sessionCookiePath="/" 


sessionCookieDomain=".provo.novell.com"> <!-- Disable session persistence 
across Tomcat restarts --> <Manager pathname="" saveOnRestart="false"/> </ 
Context> 


8 Change session proxying for setting this cookie. 
8a Navigate to Devices > Identity Servers > Edit > Options. 
8b Click New. Specify the following details: 
Property Name: Select CLUSTER COOKIE DOMAIN 
Property Value: Specify.provo.novell.com 
Property Name: Select CLUSTER COOKIE PATH 
Property Value: Specify / 


NOTE: Before you go to the next step, ensure that you have configured X.509 class, 
method, and contract. For more information, see Section 5.1.8, “Mutual SSL (X.509) 
Authentication,” on page 399. 
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9 For X509Class based redirection, in the X.509 method add the property for X.509 to be 
redirected to the new connector as follows. 


Property Name: CONNECTOR_HOST Property Value: https:// 
onbox.provo.novell.com:8448/ 


Here, the DNS name onbox is a sub domain as indicated in the prerequisite. 
10 Restart Tomcat using the following commads. 
¢ Linux: /etc/init.d/novell-idp restart 
+ Windows: Enter the following commands: 
+ net stop Tomcat7 


è net start Tomcat7 
Verify the configuration as follows: 


Access Identity Server URL in browser that does not have client certificate. Access the X.509 
authentication card and verify the behavior. It must redirect to connector port 8448 and redirect back 
to original page with an Access Manager error message or error code. 


ORed Credential Class 


Access Manager includes a class that can be configured to accept any combination of name/ 
password, X.509, or RADIUS credentials. When this class executes as part of a contract, users can 
select and enter their preferred type of credential. 


For example, if a name/password credential is ORed with an X.509 credential, the user can select to 
use a certificate or to enter a name and password. As an administrator, you have decided that both 
credentials are equally secure for the protected resource the contract is protecting. 


To create an ORed credential class: 


1 Click Devices > Identity Servers > Edit > Local > Classes. 
2 Click New, then fill in the following fields: 

Display name: Specify a name for the class. 

Java class: Select NPOrRadiusOrx509Class. 


3 Click Next, then select the types of classes you want to OR. You must select at least one of the 
following: 


Use Name/Password: Select this option if you want the PasswordClass to be one of the 
authentication options available to the user. 


Use Radius: Select this option if you want the RadiusClass to be one of the authentication 
options available to the user. 


Use X509: Select this option if you want the X509Class to be one of the authentication options 
available to the user. 


4 (Conditional) If you want to use the protected version of the PasswordClass or RadiusClass, 
select the Enforce use of HTTPS option. 


5 (Conditional) If you selected the Use Name/Password option, configure the properties: 
5a In the Name/Password Properties section, click New. 
5b Specify a property name and property value. 


For information about the properties that the PasswordClass and the 
ProtectedPasswordClass support, see “Specifying Common Class Properties” on page 373. 


404 Configuring Authentication 


5c Click OK. 
5d Repeat Step 5a through Step 5c to add more than one property. 
6 Click Next. 
7 (Conditional) If you selected the Use Radius option, configure the Radius properties. 


For information about the configuration options, see Section 5.3.2, “RADIUS Authentication,” on 
page 647. 


8 (Conditional) If you selected the Use X509 option, configure how the certificate is validated. 


For information about the configuration options, see Section 5.1.8, “Mutual SSL (X.509) 
Authentication,” on page 399. 


9 Click Next. 
10 (Conditional) If you selected the Use X509 option, configure the attribute mappings. 


For information about the configuration options, see Section 5.1.8, “Mutual SSL (X.509) 
Authentication,” on page 399. 


11 Click Next. 
12 Click Finish. 
13 Continue with creating a method and a contract for this class. 


For configuration information, see Section 5.1.3, “Configuring Authentication Methods,” on 
page 377 and Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


The Radius class prompts the user for a token instead of a password. The user can use the 
drop-down menu to select between the password and the token. If the user selects to send a 
certificate, the username and password/token options become unavailable. 


5.1.10 OpenID Authentication 


OpenID is an open, decentralized method for identifying users which allows users to use the same 
digital identity for logging in to multiple services. You can configure Identity Server to trust the provider 
or providers of OpenIDs by configuring the OpenID class. You then configure a method and contract 
and assign a protected resources to use the contract for authentication. When the users supply the 
OpenID, they are granted access if Identity Server has been configured to trust the provider of the 
OpenID server. 


NOTE: Access Manager supports OpenlD1.1. 


1 Click Devices > Identity Servers > Edit > Local > Classes. 
2 Click New, then fill in the following fields: 

Display name: Specify a name for the class. 

Java class: Select OpenldClass. 

The Java class path is configured automatically. 
3 Click Next, then configure the following properties: 


Open ID Provider Substrings: Specify at least one URL substring of an OpenID provider. The 
OpenID URL that user enters during the login process must contain one of the strings as a 
subset of the OpenID URL. For example, if user enters https: //user123.myopenid.com, this 
field needs to contain one of the following strings: 


myopenid.com 
.myopenid.com 
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To specify multiple URLs, separate them with a semicolon (;) 


Identity the OpenID user locally: After the user authenticates at the OpenID provider, Access 
Manager can associate a username from the user store with the OpenID user. With this 
association, Access Manager can use the policies defined for the username to enforce access to 
protected resources. 


+ When this option is not selected, the OpenID user is not mapped to a local user. The 
username of the authenticated user remains as the OpenID URL. For example, if the user 
enters http://user123.myopenid.com for the URL, http ://user123.myopenid.com 
becomes the username. 


+ When this option is selected, an attempt is made to map the OpenID user with a username 
in the user store. You can do this manually by storing the user’s OpenID in the attribute 
specified in the LDAP Attribute Name option. You can also have Identity Server add the 
OpenID value to the attribute by selecting the Auto Provision LDAP Attribute option. 


LDAP Attribute Name: Specify the name of the attribute that contains the identification 
information for the users. For OpenID authentication, this attribute must contain the OpenID for 
the user. 


Auto Provision LDAP Attribute: Select this option when you want the user to provide 
additional information for identification for the first authentication, such as a username and 
password. Identity Server uses this information to identify the user, then writes the user’s 
OpenID value to the attribute specified in the LDAP Attribute Name option. On subsequent 
logins, Identity Server can identify the user by using the specified attribute and the user is not 
prompted for additional information. 


4 Click Finish. 
5 Create a method for this class. 

For instructions, see Section 5.1.3, “Configuring Authentication Methods,” on page 377. 
6 Create a contract for the method: 

For instructions, see Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


If you want the user’s credentials available for Identity Injection policies, add the password fetch 
method as a second method to the contract. For more information about this class and method, 
see Section 5.1.11, “Password Retrieval,” on page 406. 


7 Update Identity Server. 


Password Retrieval 


If you have configured contracts that do not use a username and password for the credentials and 
you want to configure single sign-on to protected resources that require a user’s name and password, 
you can use the PasswordFetchClass to retrieve the user's name and password. 


You need to create the class, then create a method from the class. Assign this method as the second 
method to the authentication contract that does not prompt for the username and password. When 
Identity Server executes the contract, the PasswordFetchClass retrieves the username and 
password and stores these with the LDAP credentials, which makes them available for Identity 
Injection and Form Fill policies. 


For example, your contract is using Kerberos or X.509 certificate authentication where the password 
is not available. Use the PasswordFetchClass to retrieve the username and password. 


IMPORTANT: The PasswordFetchClass works only with eDirectory user stores. 
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Perform the following steps: 


1 Click Devices > Identity Servers > Edit > Local > Classes. 

2 Click New, specify a name for the class, and then select PasswordFetchClass in Java class. 
The Java class path is configured automatically. 

3 Click Next, then configure the following general properties: 


Ignore password retrieval failure: Select this option if you want users to continue with their 
sessions when Identity Server cannot retrieve their passwords. If this option is not selected, 
users are denied access when their passwords cannot be retrieved. 


Retain Previous Principal: Select this option to retain the principal obtained from the previous 
authentication method. If you do not select this option, then the principal will be used from the 
method associated with this class. 


Password to be retrieved: If your users have been configured to use a universal password, 
select Universal Password. Otherwise, select Simple Password. 


NOTE 


¢ Set the Universal Password Retrieval options in the configuration of the Universal Password 
policy, so that the policy allows the password to be retrieved from the user store. 


+ User must reset the password after configuring the password policy for universal password. 


For more information about unable to retrieve universal password from eDirectory by using 
PasswordFetchClass issue, see TID 7007114. 


The user object must be looked up and found in an eDirectory user store for retrieval to succeed. 
This is done by matching the currently authenticated user by using the CN attribute. If your CN 
does not match in both of your directories (common when using Active Directory and eDirectory), 
then use the DN of the user to locate the matching user object. When NetIQ Identity Manager is 
used between Active Directory and eDirectory, you will find the Active Directory DN value 
populated in the DirXML-ADContext attribute, which can be used for lookup or matching. If no 
attribute has the DN value populated, then use the Auto Provision feature. 


4 Configure the following userstore lookup settings: 


Based on the CN of the user object: CN of users are mapped between two different user 
stores. CN is mapped with for retrieving the password from the user store. For example, Active 
Directory CN is mapped with eDirectory CN for retrieving the password from the eDirectory user 
store. 


Based on the Attribute value of the user object: The user names are detected and handled 
in the LDAP attribute or DN of users of the Active Directory are mapped with LDAP attribute of 
the eDirectory. If you select this option, then specify the attribute value in attribute details of the 
Attribute name of DN and select Auto Provision if required. 


Attribute Name of the DN: Specify the attribute name of DN. 


This attribute must contain CN of user whose password you want to obtain. For example, if you 
are trying to obtain a password from eDirectory for a user with cn=a,dc=b, then you need to 
specify name of the attribute, which value is cn=a,dc=b.The passwordfetchclass tries fetching 
the password from the current user store based on the value of the LDAP attribute specified, 
which are mapped to user's DN of in Active Directory. 


Auto Provision: If you select this option, the passwordfetchclass tries fetching the password 
from LDAP attribute specified which has the value of the DN users of Active Directory and 
retrieves the password, else it prompts to log in to eDirectory. If the login is successful, then the 
LDAP attribute value gets populated with the DN user of Active Directory. When the user is 
logged next time, the same value is used. 
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5 Click OK. 
6 Create a method for this class. 
For instructions, see Section 5.1.3, “Configuring Authentication Methods,” on page 377. 


7 Assign the password fetch method as the second method for a contract that is using one of the 
following methods: 


¢ RADIUS. See “RADIUS Authentication” on page 647. 

+ X.509. See “Mutual SSL (X.509) Authentication” on page 399. 

+ OpenID. See “OpenID Authentication” on page 405. 

+ Smart Card. See “Configuring Access Manager for NESCM” on page 408. 
+ Kerberos. See “Kerberos Authentication” on page 412. 


+ Time-Based One-Time Password. See “Two-Factor Authentication Using Time-Based One- 
Time Password” on page 645 


8 Click Apply and update Identity Server. 


5.1.12 Configuring Access Manager for NESCM 


To use a smart card with Access Manager, you need to configure Access Manager to use the 
eDirectory server where you have installed the Novell Enhanced Smart Card Login Method for NMAS 
(NESCM). You then need to create a contract that knows how to prompt the user for the smart card 
credentials. The last task is to assign this contract to the protected resources that you want protected 
with a smart card. The following sections describe the prerequisites and the tasks: 


¢ Section 5.1.12.1, “Prerequisites,” on page 408 

¢ Section 5.1.12.2, “Creating a User Store,” on page 409 

¢ Section 5.1.12.3, “Creating a Contract for the Smart Card,” on page 410 

¢ Section 5.1.12.4, “Assigning the NESCM Contract to a Protected Resource,” on page 411 
¢ Section 5.1.12.5, “Verifying the User’s Experience,” on page 412 

¢ Section 5.1.12.6, “Troubleshooting,” on page 412 


5.1.12.1 Prerequisites 


O Ensure that you can authenticate to the eDirectory server by using the smart card from a 
workstation. 


+ The NESCM method needs to be installed on the eDirectory server and the workstation. 
See “Installing the Method” (http://www.novell.com/documentation/iasclient30x/ 
nescm_install/data/b7gx5la.html) in the Novell Enhanced Smart Card Method Installation 
and Administration Guide (http://www.novell.com/documentation/iasclient30x/ 
nescm_install/data/bookinfo.html). 


+ The NESCM method needs to be configured. See “Configuring the Server” (http:// 
www.novell.com/documentation/iasclient30x/nescm_install/data/b7tf2gi.html) in the Novell 
Enhanced Smart Card Method Installation and Administration Guide (http:// 
www.novell.com/documentation/iasclient30x/nescm_install/data/bookinfo.html). 


+ Provision your smart card according to your company policy. 


O Ensure that you have a basic Access Gateway configuration with a protected resource that you 
want to protect with a smart card. For more information, see Installing Access Manager in the 
NetIQ Access Manager 4.3 Installation and Upgrade Guide. 
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5.1.12.2 Creating a User Store 


Identity Server must be configured to use the eDirectory replica where you have installed the NESCM 
server method. 


+ If you have already configured Identity Server to use this replica, skip this section and continue 
with “Creating a Contract for the Smart Card” on page 410. 
¢ If your Identity Server is using a different user store, you need to configure Identity Server. 


To configure Identity Server for the eDirectory replica that has the NESCM method: 


1 Click Devices > Identity Servers > Edit > Local> User Stores > New. 
2 On the Create User Store page, fill the following fields: 
Name: A display name for the eDirectory replica (for example, nescm_replica). 


Admin Name: The distinguished name of the admin user of the directory. Administrator-level 
rights are required for setting up a user store. 


Admin Password and Confirm Password: The password for the admin user and the 
confirmation for the password. 


NOTE: If the admin account's password needs to be changed in the LDAP directory due to some 
issue, then change the admin password in the Create User Store page accordingly and apply the 
change. Else, this admin account of the user store will get locked. 


Directory Type: Select eDirectory. 
3 In the Server replica section, click New, and fill the following fields: 
Name: The display name for the LDAP directory server (for example, nescm_server). 


IP Address: The IP address of the LDAP directory server. The port is set automatically to the 
standard LDAP ports. 


4 Click Use secure LDAP connections. You must enable SSL between the user store and Identity 
Server. The port changes to 636, which is the secure LDAP port. 


Click Auto import trusted root. 
Click OK to confirm the import. 
Select the Root CA Certificate to trust any certificate signed by that certificate authority. 
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Specify an alias, then click OK. 
An alias is a name you use to identify the certificate used by Access Manager. 
9 Click Close, then click OK. 
10 Under Server Replicas, verify the Validation Status. 
The system displays a green check mark if the connection is valid. 
11 Set up a search context. 
12 Click Finish to save the information. 
13 Continue with “Creating a Contract for the Smart Card” on page 410. 
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Creating a Contract for the Smart Card 


You need to create a contract that uses the NESCM method. To do this, you need to first create an 
NMAS class, then a method that uses that class. The last task is to create a contract that uses the 
method. The following sections describe these tasks: 

¢ “Creating an NMAS Class for NESCM” on page 410 

e “Creating a Method to Use the NMAS Class” on page 410 

e “Creating an Authentication Contract to Use the Method” on page 411 


Creating an NMAS Class for NESCM 


When you create a class, you can specify values for properties. In the following steps, you specify a 
property value that determines the sequence of login prompts that the user receives when 
authenticating with a smart card. 

Click Devices > Identity Servers > Edit > Local > Classes > New. 

Specify a display name for the class (for example, Class-NMAS-NESCM). 

For the Java class, select NMASAuthClass from the selection list. 

Click Next. 

On the Specify Properties page, click New. 
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Specify the following values for the property: 
Property Name: Specify NMAS_LOGIN_SEQUENCE 
Property Value: Specify Enhanced Smart Card 


The Property Value matches the method name as displayed in the NMAS task > NMAS Login 
Methods. 


7 Click OK, then click Finish. 
8 Continue with “Creating a Method to Use the NMAS Class” on page 410. 


Creating a Method to Use the NMAS Class 


When you create a method, you can specify property values that are applied to just this method and 
not the entire class. In this tutorial, we want the method to use the same login sequence as the class. 
The method also allows you to specify which user stores can use the method. For a smart card 
method, you need to ensure that the user store or stores specified for the method have NESCM 
installed. 

1 On the Local page for Identity Server, click Methods > New. 

2 Specify a Display name (for example, Method-NMAS-NESCM). 


3 From the Class selection list, select the class created in “Creating an NMAS Class for NESCM” 
on page 410. 


4 In the Available user stores list, select the user store created in “Creating a User Store” on 
page 409, then click the left-arrow to move this user store into the User stores list. 


Leave other settings on this page unchanged. 
5 Click Finish. 
6 Continue with “Creating an Authentication Contract to Use the Method” on page 411. 
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Creating an Authentication Contract to Use the Method 


Contracts are the element you can assign to a protect a resource. 


1 


On the Local page for Identity Server, click Contracts > New. 


2 Specify a Display name (for example, Contract -NMAS-NESCM-UserStore1). 


3 Enter a URI (for example, nescm/test/uri). 


The URI is used to identify this contract for external providers and is a unique path value that you 
create. 


In the Available methods list, select the method created in “Creating a Method to Use the NMAS 
Class” on page 410, then click the left-arrow to move this method into the Methods list. 


All other fields can remain in the default state. 


(Conditional) If you want the user’s credentials (username and password) to be available for 
Identity Injection policies, add the password fetch method as a second method for the contract. 


For more information about this method and class, see Section 5.1.11, “Password Retrieval,” on 
page 406. 


Click Next, then configure a card for the contract by filling in the following fields: 


ID: (Optional) Specify an alphanumeric value that identifies the card. If you need to reference 
this card outside of Administration Console, you need to specify a value here. If you do not 
assign a value, Identity Server creates one for its internal use. 


Text: Specify the text that is displayed on the card to the user, for example Smart Card. 


Image: Select the image to display on the card. You can select the NMAS Biometrics image or 
you can select the Select local image option and upload an image that your users can associate 
with using this smart card authentication contract. 


Show Card: Determine whether the card is shown to the user, which allows the user to select 
and use the card for authentication. If this option is not selected, the card is only used when a 
service provider makes a request for the card. 


Click Finish, then click OK. 


8 Update Identity Server. 


9 Update Access Gateway. 


10 


Continue with “Assigning the NESCM Contract to a Protected Resource” on page 411 


Assigning the NESCM Contract to a Protected Resource 


Contracts must be created before they can be assigned to protected resources. The following steps 
explain how to assign the NESCM contract to an existing protected resource. If you have not created 
a protected resource, see Section 3.8.4, “Configuring Protected Resources,” on page 128. 


1 


2 


3 


Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 


The reverse proxy must be configured with a resource that you want to protect with the smart 
card. 


Click the Protected Resource link for the proxy service where you want to assign the NESCM 
contract. 


To enable the NESCM contract on an existing protected resource, click the Authentication 
Procedure link for that resource, then select the NESCM contract created in “Creating an 
Authentication Contract to Use the Method” on page 411. 
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5.1.12.6 


5.1.13 


If the contract is not listed, ensure that you have updated the changes to the servers, first to 
Identity Server and then Access Gateway. If you have multiple Identity Server configurations, 
ensure that Access Gateway is assigned to Identity Server configuration that contains the 
NESCM contract (click Access Gateways > Edit > Reverse Proxy / Authentication). 


4 Click OK. 
5 Click the Access Gateways task, then update Access Gateway. 
6 Continue with “Verifying the User’s Experience” on page 412. 


Verifying the User’s Experience 


1 From the smart-card-equipped workstation, browse to and select the URL of the proxy service 
where the protected resource requiring NESCM type authentication is enabled. 


2 When prompted by Access Manager, enter a username. 
3 When prompted for the smart card password, enter a password (the smart card PIN). 
If the Smart Card contains a certificate that meets the defined criteria (in this example, a matching 


Subject name and trusted signing CA), the user is now successfully authenticated to the IDP and is 
connected through Access Gateway to the protected resource. 


Troubleshooting 
Error Resolution 
Authentication fails without Verify that you have configured the class and method correctly. See 


prompting the user for the token “Creating an NMAS Class for NESCM” on page 410 and “Creating a 
Method to Use the NMAS Class” on page 410. 


Certificate validation fails Verify that a trusted root object created for the signing CA of the certificate 
on the smart card exists in the eDirectory trusted root container. 


Kerberos Authentication 


Kerberos is an authentication method that allows users to log in to an Active Directory domain. This 
authentication method provides them with a token, which an Identity Server can be configured to use 
as a contract. This provides single sign-on for the user between Active Directory and Identity Server. 


Kerberos authentication is achieved using SPNEGO with GSS-API (JGSS). SPNEGO (RFC 2478 - 
Simple and Protected GSSAPI Negotiation implementation in Microsoft Windows 2000/XP/2k3/2k8) 
is a GSSAPI mechanism for extending a Kerberos single-sign-on environment to Web transactions 
and services. It lets peers determine which GSSAPI mechanisms are shared and lets them select one 
and establish a security context with it. SPNEGO's most visible use is in Microsoft's HTTP Negotiate 
authentication mechanism. 


The Kerberos module for Access Manager is implemented as additional out-of-the-box authentication 
mechanism to securely negotiate and authenticate HTTP requests for protected resources. This 
makes it possible to seamlessly authenticate (single-sign-on) to Identity Server from enterprise-wide 
Microsoft Windows Domain Logon. 


This section explains how to configure Active Directory, Identity Server, and Access Gateway for 
Kerberos authentication to a protected Web server. 
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Figure 5-4 Example Kerberos Configuration 


Active Directory Domain: ad.novell.com 
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Access Gateway 


Protected Resource for Web Server 
Contract: Kerberos contract 


Kerberos requires the following configuration tasks: 


¢ Section 5.1.13.1, “Prerequisites,” on page 413 

¢ Section 5.1.13.2, “Configuring Active Directory,” on page 414 

¢ Section 5.1.13.3, “Configuring Identity Server,” on page 416 

¢ Section 5.1.13.4, “Configuring the Clients,” on page 423 

¢ Section 5.1.13.5, “Configuring Access Gateway for Kerberos Authentication,” on page 424 


Prerequisites 
Kerberos authentication is supported for the following configuration: 
¢ Clients must be running one of the following operating systems: 


Windows XP with Internet Explorer 7 or later. Some minimal testing has been done with Internet 
Explorer 6. To make Kerberos work with Internet Explorer 6, you need to enable integrated 
Windows authentication. For information about how to enable this feature, see “Authentication 
Uses NTLM instead of Kerberos” (http://technet.microsoft.com/en-us/library/cc779070.aspx). 


Windows Vista with the latest version of Internet Explorer. 
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Windows 7 with Internet Explorer 8 or later. Be aware of the following issues: 


¢ Internet Explorer needs to have the Internet Options configured to trust the URL of Identity 
Server. 


+ The keytab file must be configured to trust more than DES encryption. If you created your 
keytab file for an earlier version of Access Manager where only DES was supported, you 
need to recreate the keytab file. For the new procedure, see “Configuring the Keytab File” 
on page 415. 


For more information about these issues, see TID 7006036 (http://www.novell.com/support/ 
viewContent.do?externalld=7006036&sliceld=1). 


¢ Active Directory must be configured to contain entries for both users and their machines. Active 
Directory must be running on Windows Server 2003 Enterprise SP2, Windows Server 2008, 
Windows Server 2008 R2, or Windows Server 2012. 


+ Active Directory and Identity Server must be configured to use a Network Time Protocol server. If 
time is not synchronized, authentication fails. 


¢ If a firewall separates the Active Directory Server from Identity Server, the firewall needs to open 
ports TCP 88 and UDP 88 so that Identity Server can communicate with the KDC on the Active 


Directory Server. 


Configuring Active Directory 


You must create a new user in Active Directory for Identity Server, set up this user account to be a 
service principal, create a keytab file, and add Identity Server to the Forward Lookup Zone. These 
tasks are described in the following sections: 

¢ “Installing the spn and the ktpass Utilities for Windows Server 2003” on page 414 

¢ “Creating and Configuring the User Account for Identity Server” on page 414 

¢ “Configuring the Keytab File” on page 415 

e “Adding Identity Server to the Forward Lookup Zone” on page 416 


Installing the spn and the ktpass Utilities for Windows Server 2003 


When you install Windows Server 2003 and Active Directory, the spn and ktpass utilities are not 
installed in a default installation. These utilities are installed in a default Windows Server 2012 
installation. 


You need the spn and ktpass utilities to configure Identity Server for Kerberos authentication. 


1 Insert the Windows 2003 CD into the CD drive. 
2 To install the utilities, run \SUPPORT\TOOLS\SUPTOOLS.MST on the CD. 
The utilities are installed in C:\Program Files\Support Tools. 


Creating and Configuring the User Account for Identity Server 
1 In Manage Your Server on your Windows server, select the Manage users and computers in 
Active Directory option. 
2 Select to create a new user. 
3 Fill in the following fields: 


First name: Specify the hostname of Identity Server. This is the username. For the example 
configuration, this is amser. 
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User logon name: Specify HTTP/<Identity_Server_Base_URL>. For this example 
configuration, your Identity Server has a base URL of amser.provo.novell.com, and you would 
specify the following for the User Logon Name: 


HTTP/amser .provo.novell.com 


The realm is displayed next to the User logon name. 


User logon name (pre Windows 2000): Specify the hostname of Identity Server. The default 
value must be modified. For the example configuration, this is amser. 


4 Click Next, and configure the password and its options: 
Password: Specify a password for this user 
Confirm password: Enter the same password. 
User must change password at next logon: Deselect this option. 
Password never expires: Select this option. 
5 Click Next, then click Finish. 


This creates Identity Server user. You need to remember the values you assigned to this user for 
First name and User logon name. 


6 To set the servicePrincipalName (spn) attribute for this user, open a command window and enter 
the following commands: 


setspn -A HTTP/<userLogonName> <userName> 
For this configuration example, you would enter the following command: 
setspn -A HTTP/amser.provo.novell.com@AD.NOVELL.COM amser 


This adds the servicePrincipalName attribute to the user specified with the value specified in the 
-A parameter. 


NOTE: For Domain Services for Windows, set HOST spn also by using this command: setspn - 
A HOST/<userLogonName> <userName> 


7 (Optional) Verify that the user has the required servicePrincipalName attribute with a valid value. 
Enter the following command: 


setspn -L <userName> 
For this configuration example, you would enter the following command: 


setspn -L amser 


Configuring the Keytab File 


The keytab file contains the secret encryption key that is used to decrypt the Kerberos ticket. You 
need to generate the keytab file and copy it to Identity Server. 


1 On the Active Directory server, open a command window and enter a ktpass command with the 
following parameters: 


ktpass /out value /princ value /mapuser value /pass value 
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The command parameters require the following values: 


Parameter Value Description 


/out <outputFilename> Specify a name for the file, with . keytab as the 
extension. For example: nidpkey. keytab 


/princ <servicePrincipalName> Specify the service principal name for Identity 
@<KERBEROS_REALM> Server, then @, followed by the Kerberos realm. 
The default value for the Kerberos realm is the 
Active Directory domain name in all capitals. The 
Kerberos realm value is case sensitive. 


/mapuser <identityServerUser>@<AD_DOMAI __ Specify the username of Identity Server user and 
N> the Active Directory domain to which the user 
belongs. 
/pass <userPassword> Specify the password for this user. 


For this configuration example, you would enter the following command to create a keytab file 
named nidpkey: 


ktpass /out nidpkey.keytab /princ HTTP/amser.provo.novell.com@AD. 
NOVELL.COM /mapuser amser@AD.NOVELL.COM /pass novell 


Copy the file to the default location on Identity Server: 
Linux: /opt/novell/java/jre/lib/security 
Windows Server 2012: C:\Program Files (x86)\Novell\jre\lib\security 


If the cluster contains multiple Identity Servers, copy the keytab file to each member of the 
cluster. 


Adding Identity Server to the Forward Lookup Zone 
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In Manage Your Server on your Windows server, click Manage this DNS server. 
Click Forward Lookup Zone. 

Click the Active Directory domain. 

In the right pane, right click, and select New Host (A). 

Fill in the following fields: 

Name: Specify the hostname of Identity Server. 

IP Address: Specify the IP address of Identity Server. 

Click Add Host. 


Configuring Identity Server 


You need to configure Identity Server to use the Active Directory server as a user store, configure a 
Kerberos authentication class, method, and contract, create a configuration file, enable logging to 
verify the configuration, then restart Tomcat. These instructions assume that you have installed and 
configured an Identity Server cluster configuration.See Installing Access Manager in the NetIQ 
Access Manager 4.3 Installation and Upgrade Guide and Section 3.4, “Identity Servers Cluster,” on 
page 62. 


+ 


+ 


“Enabling Logging for Kerberos Transactions” on page 417 


“Configuring Identity Server for Active Directory” on page 417 
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¢ “Creating the Authentication Class, Method, and Contract” on page 418 

¢ “Creating the bcsLogin Configuration File” on page 419 

¢ “Verifying the Kerberos Configuration” on page 420 

+ “(Optional) Using the Name/Password Form Authentication” on page 421 
+ “(Optional) Configuring the Fall Back Authentication Class” on page 422 


Enabling Logging for Kerberos Transactions 


Enabling logging is highly recommended. If Kerberos authentication does not function after you have 
finished the configuration tasks, the first step in solving the problem is to look at the catalina. out 
(Linux) or the stdout . log (Windows) file. 

1 Click Devices > Identity Servers > Edit > Auditing and Logging. 

2 Enable the File Logging and Echo To Console options. 

3 In the Component File Logger Levels section, set Application to debug. 

4 Click OK, then update Identity Server. 


Configuring Identity Server for Active Directory 


You need to either configure your Identity Server to use Active Directory as a user store or verify your 
existing configuration for your Active Directory user store. 

1 Click Devices > Identity Servers > Edit. 

2 Click Local. 

3 View your installed user stores. 


If you have already configured your Identity Server to use the Active Directory server, click its 
name. 


If you haven’t configured a user store for the Active Directory server, click New. 


4 For anew user store, fill in the following fields. For an existing Active Directory user store, verify 
the values. 


Name: Specify a name of the user store for reference. 


Admin name: Specify the name of the administrator of the Active Directory server. 
Administrator-level rights are required for setting up a user store. This ensures read/write access 
to all objects used by Access Manager. 


Admin password and Confirm password: Specify the password for the administrator of the 
Active Directory server and confirm the password. 


Directory Type: Select Active Directory. 


Search Contexts: For a new user store, click New and specify the context of the administrator 
of the Active Directory server. For an existing user store, verify that you have an entry for the 
context of the administrator and add one if it is missing. 


5 (Conditional) For a new Active Directory user store, add a replica. In the Server replicas section, 
click New. 


5a Fill in the following fields: 


Name: Specify a name of the replica for reference. This can be the name of your Active 
Directory server. 


IP Address: Specify the IP address of the Active Directory server and the port you want 
Identity Server to use when communicating with the Active Directory server. 
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5b Configure the other fields to fit your security model. 

5c Click OK. 
(Optional) Specify values for the other configuration options. 
To save your changes, click OK or Finish. 
Continue with “Creating the Authentication Class, Method, and Contract” on page 418. 
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1 
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In the Local page, click Classes > New. 

Fill in the following fields: 

Display name: Specify a name that you can use to identify this class. 
Java class: Select KerberosClass. 

The Java class path field displays the name of the KerberosClass. 
Click Next. 


4 Fill in the following fields: 


6 


Service Principal Name (SPN): Specify the value of the servicePrincipalName attribute of 
Identity Server user. For this example configuration, this is HTTP/amser .provo.novell.com. 


Kerberos Realm: Specify the name of the Kerberos realm. The default value for this realm is the 
domain name of the Active Directory server, entered in all capitals. The value in this field is case 
sensitive. For this example configuration, this is AD . NOVELL . COM. 


JAAS config file for Kerberos: Verify the default path. This must be the same path to which 
you copied the keytab file (see Step 2 in “Configuring the Keytab File” on page 415) and end with 
the name of the configuration file, bcsLogin.conf. 


For Windows, the path needs to contain double slashes, for example: C: \\Program 
Files\\Novell\\jre\\lib\\security 


Instructions for creating this file are in “Creating the bcsLogin Configuration File” on page 419. 
Kerberos KDC: Specify the IP address of the Key Distribution Center. If multiple KDCs are 
present for fail-over support, then specify the IP addresses separated by colon (:). Maximum of 4 
IP addresses can be configured. 


If a L4 switch is configured for load balancing between the KDCs, then enter the virtual IP 
address of the L4 switch in this field. 


User Attribute: Specify the name of the Active Directory attribute that combines the cn of the 
user with the DNS domain name to form its value. It is an alternate name for user login. Accept 
the default value unless you have set up a different attribute. 


(Conditional) If you have configured your users to have multiple User Principal Names (UPN) so 
they can log in using different names (such as jdoe@abc.com, jdoe@bcd.com, and 
jdoe@cde.com), click New, specify the suffix (such as @abc.com), then click OK. 


Click Finish. 


IMPORTANT: You must create only one Kerberos class. This is caused by a limitation in the 
underlying Sun JGSS. 


On the Local page, click Methods > New. 

Fill in the following fields: 

Display name: Specify a name that you can use to identify this method. 
Class: Select the class that you created for Kerberos. 
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User stores: Move the Active Directory user store to the list of User stores. If you have only one 
installed user store, <Default User Store> can be used. If you have multiple user stores, the 
Active Directory user store must be in this list (or if it is configured to be the default user store, 
<Default User Store> must be in this list). 


NOTE: The testing procedure to verify Kerberos authentication is dependent upon having the 
Active Directory user store configured as the default user store. See Step 13. 


You do not need to configure properties for this method. 
9 Click Finish. 

10 In the Local page, click Contracts > New. 

11 Fill in the following fields: 
Display name: Specify a name that you can use to identify this method. 
URI: Specify a value that uniquely identifies the contract from all other contracts. 
Methods: From the list of Available methods, move your Kerberos method to the Methods list. 
You do not need to configure the other contract options. 

12 Click Finish. 


13 (Optional) To use the procedure that verifies the authentication configuration, you need to make 
the Active Directory user store the default user store. In the Local page, click Defaults. 


13a Fill in the following fields: 
User Store: Select the name of your Active Directory user store. 
Authentication Contract: Select the name of your Kerberos contract. 
13b Click OK. 


This allows you to log in directly to Identity Server by using the Kerberos contract. If you 
have already logged in to the Active Directory domain on the Windows machine, single 
sign-on is enabled and you are not prompted to log in to Identity Server. 


14 On Identity Servers page, click Update. 
Wait until the Health icon turns green. Click Refresh to update the page. 


15 If you have Access Gateways or J2EE Agents that you want to configure to use the Kerberos 
contract, update these devices so that the Kerberos contract is available. 


16 Continue with “Creating the bcsLogin Configuration File” on page 419. 


Creating the bcsLogin Configuration File 
If you are upgrading from 3.1 SP2 to 3.1 SP3, the syntax of the bcsLogin.conf file has changed. 
To create the file: 


1 Open a text editor. A sample bcsLogin.con file called bcsLogin.conf.template is included that 
can be edited. Open this file. 


2 Enter the following lines. The file cannot contain any white space, only end-of-line characters. 
Two lines (principal and keyTab) need to specify unique information for your configuration. The 
principal line needs to specify the service principle name for Identity Server. The keyTab line 
needs to specify the location of the keytab file. The following file uses the values of the example 
configuration for the principal and keyTab lines. The keyTab and ticketCache lines use the 
default path for SUSE Linux Enterprise Server (SLES). 
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com.sun.security.jgss.accept { 
com.sun.security.auth.module.Krb5LoginModule required 

debug="true" 

useTicketCache="true" 
ticketCache="/opt/novell/java/jre/lib/security/spnegoTicket.cache" 
doNotPrompt="true" 

principal="HTTP/amser .provo.novell.com@AD.NOVELL.COM" 
useKeyTab="true" 
keyTab="/opt/novell/java/jre/lib/security/nidpkey. keytab" 
storeKey="true"; 


J; 


Identity Server will check the Kerberos server for each user transaction. When you set the 
isInitiator value to false (isInitiator="false") in the bcsLogin.conf file after the keyTab="/ 
opt/novell/java/jre/lib/security/nidpkey.keytab" line, Identity Server does not 
communicate to the Kerberos server. 


Path of bcsLogin.conf on SLES and Red Hat is /opt/novell/java/jre/lib/security/. 


NOTE: Before setting the value to "false", it is recommended that you access the protected site 
via https and keytab file is secure. 


For Windows, the path needs to contain double slashes: C:\\Program 
Files\\Novell\\jre\\lib\\security 


Windows Server 2012: The path in the keyTab line must be C:\\Program Files 
(x86)\\Novell\\jre\\lib\\security\\nidpkey. keytab 


The path in the ticketCache line must be C:\\Program Files 
(x86) \\Novell\\jre\\lib\\security\\spnegoTicket.cache 


3 Save this file with a name of bcsLogin.conf. 
4 Copy this file to the location specified in the JAAS config file for Kerberos field of Step 4 in 


“Creating the Authentication Class, Method, and Contract” on page 418. 


5 Ensure that the file permissions are set correctly. They must be set to 644. 
6 Restart Identity Server: 


¢ Linux Identity Server: Enter the following command: 
/etc/init.d/novell-idp restart 
+ Windows Identity Server: Enter the following commands: 
net stop Tomcat7 
net start Tomcat7 
Whenever you make changes to the bcsLogin.conf file, you need to restart Tomcat. 


If the cluster contains multiple Identity Servers, copy the bcsLogin.conf file to each member of 
the cluster, then restart Tomcat on that member. 


Verifying the Kerberos Configuration 
To view catalina. out (Linux) or the stdout . 10g (Windows) of Identity Server: 


1 Click Auditing > General Logging. 

2 In Identity Servers section, select the catalina. out or stdout . log file. 

3 Download the file and open it in a text editor. 

4 Search for Kerberos and verify that a subsequent line contains a Commit Succeeded phrase. 


For the configuration example, the lines look similar to the following: 
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principal's key obtained from the keytab 

principal is HTTP/amser.provo.novell.com@AD.NOVELL.COM 

Added server's keyKerberos Principal HTTP/ 
amser.provo.novell.com@AD.NOVELL.COMKey Version 3key Encryptionkey: keyType=3 
keyBytes (hex dump)=0000: CB OE 91 FB 7A 4C 64 FE 


[Krb5LoginModule] added Krb5Principal HTTP/ 
amser.provo.novell.com@AD.NOVELL.COM to Subject 
Commit Succeeded 


5 If the file does not contain any lines similar to these, verify that you have enabled logging. See 
“Enabling Logging for Kerberos Transactions” on page 417. 
6 If the commit did not succeed, search backward in the file and verify the following values: 
¢ Service Principal Name 
+ Name of keytab file 
For the example configuration, the file must contain lines with text similar to the following: 


Principal is HTTP/amser.provo.novell.com 
KeyTab is /usr/lib/java/jre/lib/security/nidpkey.keytab 


N 


(Conditional) If you make any modifications to the configuration, either in Administration Console 
or to the bcsLogin file, restart Tomcat on Identity Server. 


(Optional) Using the Name/Password Form Authentication 


You can configure the IP address or the range of IP addresses of the clients for which the kerberos 
authentication must be skipped or performed using the kerberos.exclude or kerberos.include 
keywords respectively. 


NOTE: You can specify only kerberos.exclude or kerberos.include argument in the 
kerb.properties file not both. 


To configure this option, add the following entry in the kerb.properties file: 


¢ kerberos.exclude=IP Address/Range separated by comma. 
+ kerberos.include=IP Address/Range separated by comma. 


For example: 


kerberos.exclude=1.1.1.1-9.255.255.255,10.50.1.1 - 10.50.1.50,11.1.1.1- 
255.255.255.255 


or 
kerberos. include=10.1.1.1-10.49.255.255,10.50.1.51-10.255.255.255 


For the clients coming from the IP addresses specified in kerberos.exclude, Kerberos 
authentication will be skipped and will fall back to the custom authentication class. See “(Optional) 
Configuring the Fall Back Authentication Class” on page 422. 


For the clients coming from the IP addresses that are not specified in kerberos.include, kerberos 
authentication will be skipped and will fall back to the custom authentication class. See “(Optional) 
Configuring the Fall Back Authentication Class” on page 422. 


The kerb.properties file is available at the following locations: 


Linux: /var/opt/novell/nids/lib/webapp/WEB-INF/classes 
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Windows Server 2012: \\Program Files (x86)\\Novell\\Tomcat \\webapps\\nidp\\WEB- 
INF\\classes 


(Optional) Configuring the Fall Back Authentication Class 


You can configure an optional authentication class that has to be executed when either kerberos 
authentication fails or when kerberos authentication has to be skipped. 


For information about how to skip the kerberos authentication for certain IP addresses, see 
“(Optional) Using the Name/Password Form Authentication” on page 421 


To configure the fall back authentication class: 
1 Go to the Identity Server Cluster > Edit > Local > Methods > (Kerberos Method) > Properties 
tab. 


2 Add anew property /value pair with name as FALLBACK_AUTHCLASS and set the property 
value to be the qualified class name such as 
com.novell.nidp.authentication.local.PasswordClass. 


The class name value must be same as the value configured in the Java class path of the class 
at IDP Cluster > Edit> Local > Classes> (Authentication class). 


NOTE: If your authentication class requires a custom JSP file for seeking credentials, add the 
property JSP and specify the name of the jsp file. When the JSP property is not specified, Identity 
Server will use the default login.jsp for seeking the credentials. 


If you want to fall back to basic authentication, configure any one of the following properties: 
Property Name: FALLBACK_AUTHCLASS 


Property Value: Basic or com.novell.nidp.authentication.local.BasicClass 


NOTE: The property name is case-sensitive. 


For example, if you want to fall back to Radius, configure the following properties for the kerberos 
method: 


FALLBACK_AUTHCLASS=com.novell.nidp.authentication.local.RadiusClass JSP=radiusloginServ 
er=<<radius IPs with comma separate>>SharedSecret=<<secret 
string>>Port=<<port>>ReplyTime=7000 (in milli seconds, this is 
optional)ResendTime=2000 (in milli seconds, this is optional)Retry=5 (this is 
optional )Password=false 


NOTE: The property name is case-sensitive. 


Also, you can configure fall back to other mechanism based on the incoming header. In the kerberos 
Method, add the name/value in the property field with name as NO_.NEGO_HEADER_NAME and in 
the value filed you can provide the header, which needs to be ignored for the kerberos authentication. 


For Example, in the kerberos method properties, if you configure the name as 
NO_NEGO_HEADER_NAME with value X-NovINet. Then if the client comes with header X-NovINet, 
the kerberos class will not be executed and it will fall back to the name password form by default or to 
the configured fall back mechanism. 
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5.1.13.4 Configuring the Clients 


1 Add the computers of the users to the Active Directory domain. 
For instructions, see your Active Directory documentation. 
2 Log in to the Active Directory domain, rather than the machine. 


3 (Conditional) If you are using Internet Explorer, configure the web browser to trust Identity 
Server: 


3a Click Tools > Internet Options > Security > Local intranet > Sites > Advanced. 


3b In the Add this website to the zone text box, enter the Base URL for Identity Server, then 
click Add. 


In the configuration example, this is http: //amser .provo.novell.com. 
3c Click Close > OK. 
3d Click Tools > Internet Options > Advanced. 
3e In the Security section, select Enable Integrated Windows Authentication, then click OK. 
3f Restart the browser. 
4 (Conditional) If you are using Firefox, configure the Web browser to trust Identity Server: 
4a In the URL field, specify about : config. 
4b In the Filter field, specify network.n. 
4c Double click network.negotiate-auth.trusted-uris. 


This preference lists the sites that are permitted to engage in SPNEGO Authentication with 
the browser. Specify a comma-delimited list of trusted domains or URLs. 


For this example configuration, you would add http: //amser .provo.novell.com to the 
list. 


4d If the deployed SPNEGO solution is using the advanced Kerberos feature of Credential 
Delegation, double-click network.negotiate-auth.delegation-uris. This preference 
lists the sites for which the browser can delegate user to the server. Specify a comma- 
delimited list of trusted domains or URLs. 


For this example configuration, you would add http: //amser .provo.novell.com to the 
list. 


4e Click OK, then restart your Firefox browser. 
5 In the URL field, enter the base URL of Identity Server with port and application. For this 
example configuration: 
http://amser.provo.novell.com:8080/nidp 
Identity Server must authenticate the user without prompting the user for authentication 
information. If a problem occurs, check for the following configuration errors: 
+ Verify the default user store and contract. See Step 13. 


¢ View Identity Server logging file and verify the configuration. See “Verifying the Kerberos 
Configuration” on page 420. 


¢ If you make any modifications to the configuration, either in Administration Console or to the 
bcsLogin file, restart Tomcat on Identity Server. 
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5.1.14 


5.1.14.1 


5.1.14.2 


6 (Conditional) If you have users who are outside the firewall, they cannot use Kerberos. SPNEGO 
defaults first to NTLM, then to HTTPS basic authentication. Access Manager does not support 
NTLM, so the NTLM prompt for username and password fails. The user is then prompted for a 
username and password for HTTPS basic authentication, which succeeds if the credentials are 
valid. 


To avoid these prompts, you can have your users enable the Automatic logon with current user 
name and password option in Internet Explorer 7.x. To access this option, click Tools >Internet 
Options >Security >Custom Level, then scroll down to User Authentication. 


Configuring Access Gateway for Kerberos Authentication 


If you have set up a Web server that you want to require Kerberos authentication for access, you can 
set up a protected resource for this Web server as you would for any other Web server, and select the 
name of your Kerberos contract for the authentication procedure. For instructions, see Section 3.8.4, 
“Configuring Protected Resources,” on page 128. 


When using Kerberos for authentication, the LDAP credentials are not available. If you need LDAP 
credentials to provide single sign-on to some resources, see Section 5.1.11, “Password Retrieval,” on 
page 406. 


Managing Direct Access to Identity Server 


Users usually log into Identity Server when they request access to a Web resource. Access Gateway 
redirects users from the resource to Identity Server to provide the required credentials for the 
resource. After they are authenticated, they are not prompted for credentials again, unless a resource 
requires credentials that they haven't already supplied. 


Users can log directly into Identity Server and access either the default user portal or the legacy user 
portal. Alternatively, they can access information about the available Web Services Description 
Language (WSDL) services. 


Logging in to the Default User Portal 


Access Manager 4.2 default user portal page is the user portal page that contains appmarks. This is a 
different portal page than for prior release. For more information, see Access Manager 4.3 Release 
Notes. 


User log directly in to Identity Server through the default user portal page when they access the 
following URL: 


https://NAM-Base-URL :8443/nidp/portal 


IMPORTANT: The Access Manager domain name for the IDP must be resolvable through DNS or the 
hosts file on the IDP. 


You can customize the default user portal page through Branding in Administration Console. For 
more information, see Section 7.8, “Changing the Branding of the User Portal Page,” on page 706. 


Logging in with the Legacy Customized Portal 


If you have customized the legacy user portal page, and want to keep the customized pages, you 
must perform some manual steps. For more information, see Maintaining Customized JSP Files for 
Identity Server. 
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5.1.14.4 


Managing Authentication Cards 


The default user portal page prompts the user to authentication with the credentials required for the 

default contract. When users log directly into Identity Server, the users must use the default card for 
authentications. The menu in the top left corner displays all available cards, when the users click the 
menu. 


On a newly installed system, the menu displays cards for all the authentication contracts that are 
installed with the system. To avoid confusing your users, you need to disable the Show Card option 
for the contracts you do not want your users to use. Also, ensure that you modify the default contract 
to match a card that Administration Console displays. 


If you display multiple cards, users can use different credentials to authenticate multiple times by 
selecting another authentication card and entering the required credentials. This is only useful if the 
credentials grant the user different roles or authorize access to different resources. 


If you have configured Identity Server to be a service provider and have established a trusted 
relationship with one or more identity providers, the cards of these trusted identity providers appear in 
the menu under REMOTE LOGINS, Your users can use the identity provider's authentication card to 
federate their account at the identity provider with their account at the service provider. When they 
federate an account, they are telling the service provider to trust the authentication established at the 
identity provider. This enables single sign-on between the providers. The card can also be used to 
defederate the accounts. On the authentication card, click Defederate. 


If you have configured Identity Server to be an identity provider for service providers, in the menu in 
the upper right corner of the user portal page contains a Federations options that displays a 
Federations page. From this page, users can federate and deferated their accounts with trusted 
service providers. 


To edit the default contracts: 


1 Log in to Administration Console. 


2 Click Devices > Identity Servers > Edit > Local > Contracts > Name of Contract > 
Authentication Card. 


3 Unselect the Show Card option, then click OK to save the change. 

4 On the Local page for the Identity Service, click Defaults. 

5 Modify the contract to match the cards that Administration Console displays. 
6 Click OK to save the changes. 


Specifying a Target 


You can specify a target for the new and legacy user portal pages. You must specify a target for the 
following conditions: 


e You want to direct the users to a specific URL after the users log in to Identity Server. 
+ You do not want users to have access to the user portal page. 


Use one of the following methods to specify the target: 


¢ Specify a Target in the URL: You can have your users access Identity Server with a URL that 
contains the desired target. For example: https: //domain.com:8443/nidp/ 
app?target=http: //www.acme.com 


where domain.com is the DNS name of your Identity Server. In this example, the users would 
see the Acme Web site after logging in. 
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¢ Specify a Hidden Target on your Form: If you have your own login form to collect credentials 
and are posting these credentials to Identity Server, you can add a hidden target to your login 
form. When authentication succeeds, Access Manager directs the user to this target URL. This 
entry on your form should look similar to the following: 


<input type="hidden" target="http://www.acme.com"> 


These methods work only when the user's request is for the user portal (/nidp/portal or / 
nidp/app). If the user’s request is a redirected authentication request for a protected resource, 
the protected resource is the target and cannot be changed. 


Blocking Access to the User Portal Page 


This information is for the legacy user portal page only. You cannot block the default user portal page. 


If a user is already authenticated and accesses Identity Server, the user is presented with Identity 
Server user portal page. 


This page provides information about the logged-in user: 


+ Any federations this user has established with third-party service providers 


¢ Identity attributes such as Liberty Personal or employee profile attributes, Access Manager 
credential, or custom profile attributes 


¢ Policy attributes that users or administrators have selected to share with other service providers 
You might want to prevent users from seeing this page for the following reasons: 


¢ Security: Users accessing this page have access to sensitive information that administrators 
might want to restrict such as the user’s attributes and federations with other third-party SAML or 
Liberty providers. 


+ Help Desk Support: Most users have no need to access the information presented in this page. 
As a result, they might be confused if they see it. By preventing access to the page, any potential 
calls into the help desk are avoided. 


When you enable the legacy, mode. all end user login pages use the legacy UI. However, there are 
several places where Access Manager issues the URL/nidp and shows the portal page. This is 
because in the index.html file for the nidp webapp there is a redirect from /nidp to /nidp/portal. 


To block the legacy user portal page: 


1 Ensure that you create the WEB- INF/legacy directory. For more information, see “Logging in 
with the Legacy Customized Portal” on page 424. 


2 As a system administrator, edit the /webapp/index.htm1 file. 
3 Change the line: 


<meta http-equiv="refresh" content="0; URL=portal"> 
to: 
<meta http-equiv="refresh" content="0; URL=app"> 

4 Save the /webapp/index.htm1 file. 


After this change takes place, the only way to access the legacy user portal page is to enter the URL 
in the browser of /nidp/portal. 
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5.1.14.6 Blocking Access to the WSDL Services Page 


Users can access the WSDL services page when they enter the base URL of Identity Server in their 
browsers with the path to the Services page. For example, if your base URL is http: // 
bfrei.provo.novell.com:8080/nidp, the users can access the services page by using http:// 
bfrei.provo.novell.com:8080/nidp/services. 


The Services page contains the following information and links: 


Figure 5-5 WSDL Services Page 


= Access Manager 


Nidp Web Services List 


IDSISCredentialProfile (View WSDL) 
Query 
QueryOperation 
Modify 
ModifyOperation 


IDSISAuthenticationProfile (View WSDL) 
Query 
QueryOperation 
Modify 
ModifyOperation 


DiscoveryService (View WSDL) 


Query 
Modify 
processRequest 


LDAPService (View WSDL) 
Query 
QueryOperation 
Modify 
ModifyOperation 


System Properties: 
Name: axis.EngineConfigF actory 
Value: com.novell.nidp liberty.wsf.axis.NIDPAxisEngineConfigF actory 


Access Manager Home Page 


The amount of information displayed on this page depends upon the profiles you have enabled. To 
enable profiles, click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 


If you do not want your users to have access to this page, you can block access. 


1 Click Devices > Identity Servers > Edit > Options. 
2 Click New. Specify the following details: 
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Property Type Property value 


Select WSF SERVICES LIST. Select full to enable users to access the Services 
page. 


Select 404 to return an HTTP 404 status code: Not 
Found 


Select 403 to return an HTTP 403 status code: 
Forbidden 


Select empty to return an empty services list 


3 Restart Tomcat for your modifications to take effect: 


Linux: Enter one of the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 

Windows: Enter the following commands: 
net stop Tomcat7 


net start Tomcat? 


5.2 Federated Authentication 


Federation allows a user to associate two accounts with each other. This allows the user to log into 
one account and access the resources of the other account without logging in to the second account. 
It is one method for providing single sign-on when a user has accounts in multiple user stores. 


+ 


+ 


Section 5.2.1, “Configuring Federation,” on page 429 

Section 5.2.2, “Service Provider Brokering,” on page 448 

Section 5.2.3, “Configuring User Identification Methods for Federation,” on page 464 
Section 5.2.4, “Configuring SAML 2.0,” on page 471 

Section 5.2.5, “Configuring SAML 1.1,” on page 506 

Section 5.2.6, “Configuring Liberty,” on page 509 

Section 5.2.7, “Configuring Liberty Web Services,” on page 516 

Section 5.2.8, “Configuring WS Federation,” on page 535 

Section 5.2.9, “Configuring WS-Trust Security Token Service,” on page 559 

Section 5.2.10, “Configuring OAuth and OpenID Connect,” on page 581 


Section 5.2.11, “Configuring Authentication Through Federation for Specific Providers,” on 
page 616 


Section 5.2.12, “Integrating Amazon Web Services with Access Manager,” on page 620 
Section 5.2.13, “Configuring Single Sign-On for Office 365 Services,” on page 622 
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5.2.1.1 


Configuring Federation 


This section describes what is federation, how to configure federation, and how to set up federation 
with third-party providers. Topics include: 


¢ Section 5.2.1.1, “Understanding a Simple Federation Scenario,” on page 429 

¢ Section 5.2.1.2, “Configuring Federation,” on page 430 

¢ Section 5.2.1.3, “Sharing Roles,” on page 441 

¢ Section 5.2.1.4, “Setting Up Federation with Third-Party Providers,” on page 447 


Understanding a Simple Federation Scenario 


Suppose Company A has a centralized user store that does the authentication for most of the 
company’s internal resources on its inner Web site. But Company A also has a customer feedback 
application that employees and customers need access to, and for this application, a second user 
store has been created. This user store contains both employee and customer user accounts. The 
centralized user store cant be used, because it can contain only employee accounts. This means that 
the employee must log in to both accounts to access both the inner Web site and the customer 
feedback application. With federation, the employee can access the resources of both sites by using 
a single login. 


Figure 5-6 illustrates such a network configuration where the user accounts of Site A are configured 
to federate with the user accounts at Site B. 


Figure 5-6 Using Federated Identities 
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5.2.1.2 


In this configuration, Site A is Identity Server for the corporate resources, and the employees 
authenticate to this site and have access to the resources on the Web server with the URL of 
https://provo.novell.com/inner. Site B is Identity Server for the Bugzilla application, and both 
employees and customers authenticate to this site to have access to the resources of the Web server 
with the URL of https://provo.novell.com/bugz. After an account has been federated, the user 
can log in to Site A and have access to the resources on the Web servers of both Site A and Site B. 


In this scenario, Site B is not as secure a site as Site A, so federation is configured to go only one 
way, from Site A to Site B. This means that users who log in to Site A have access to the resources at 
Site A and B, but users who log in to Site B have access only to the resources at Site B. Federation 
can be configured to go both ways, so that it does not’matter whether the user logs into Site A or Site 
B. When federation is configured to be bidirectional, both sites need to be equally secure. 


Access Gateways in Figure 5-6 are service providers and are configured to use Identity Servers as 
identity providers. The trusted relationship is automatically set up for you when you specify 
authentication settings for Access Gateway and select an Identity Server Cluster. 


Federation can be set up between providers in the same company or between providers of separate 
companies. For example, most companies have contracts with other companies for their user’s health 
benefits and retirement accounts. Their users have accounts with these companies. These accounts 
can be federated with the user’s employee account when both companies agree to set up the trusted 
relationship. 


Configuring Federation 


Federation requires the configuration of a trusted relationship between an identity provider and a 
service provider. Figure 5-7 illustrates setting up federation between two identity servers, because a 
Access Manager Identity Server can act as either an identity provider or a service provider. 


Figure 5-7 Configuring Trust Between Site A and Site B 


Identity Server Identity Server 
Site A Site B 


a a 


Identity Provider: A Identity Provider: B 
DNS: idp.sitea.novell.com Service Provider: 1 
DNS: idp.siteb.novell.com 


Site A must be configured to trust Site B as a service provider, and Site B must be configured to trust 
Site A as an identity provider. Until this two-way trust is established, federation cannot occur. 


Before setting up a trusted relationship, you must make the following decisions: 


Protocol: Identity Server supports SAML 1.1, SAML 2.0, and Liberty. You need to decide which of 
these protocols to use. If no user interaction is needed, SAML 1.1 is probably a good choice. The 
SAML 2.0 and Liberty protocols permit user interaction when federating. The user decides whether to 
federate (link) the accounts and must be logged in at both sites to accomplish this. Liberty offers an 
additional service, not available with SAML 2.0, that allows the user to select attributes that can be 
shared with the service provider. 


The instructions in this documentation, starting in “Prerequisites” on page 431, use the Liberty 
protocol. They also indicate how to configure for the SAML 2.0 and SAML 1.1 protocols. 
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Trust Relationship: You need to decide whether the trusted relationship is going to be from Site A to 
Site B, from Site B to Site A, or bidirectionally from Site A to Site B and from Site B to Site A. 
Federation is set up to go from the most secure site to the less secure site. The only time federation is 
set up to be bidirectional is when both sites are equally secure. The scenario described in Figure 5-6 
on page 429 is an example of a trusted relationship that you would want to go only one way, from Site 
A to Site B, because Site B is not as secure as Site A. 


The instructions, starting in “Prerequisites” on page 431, explain how to set up the trusted relationship 
between Site A and Site B. You can easily modify them to set up the bidirectional trust relationships 
by substituting Site B for Site A (and vice versa) in the instructions and then repeating them for Site B 


Attributes to Share: You need to decide whether there are user attributes or roles at Site A that you 
want to share with Site B. The attributes from Site A can be used to identify the users at Site B. Other 
attributes might be needed to access protected resources, for example, to satisfy the requirements of 
an Identity Injection policy. 


For all the protocols, “Sharing Roles” on page 441 explains how to share the roles at Site A with Site 
B. For the SAML 1.1 protocol, the instructions starting in “Prerequisites” on page 431 use the LDAP 
mail attribute to share the user’s e-mail address. 


User Identification: You need to decide how assertions can be used to map users from Site A to 
users at Site B. Identity Server supports four methods: 


¢ Temporary: This method allows the user access to Site B solely from the credentials of Site A. 
No effort is made to map the user to a user account at Site B. A temporary account is set up for 
the user on Site B, and when the user logs out, the account is destroyed. 


¢ Login: This method requires that the user have login credentials at both Site A and Site B, and 
when logged in at both sites, the user can select to federate the accounts. 


+ Mapped Attributes: This method requires that the sites share attributes and that these 
attributes are used to create a matching expression that determines whether the user accounts 
match. For an added security check, the first time the accounts are matched, the user is asked to 
verify the match by supplying the password for Site B. 


If the match fails, you can allow the federation to fail or you can configure the method to allow the 
user to use the Login method or the Provisioning method. 


¢ Provisioning: This method allows the user to create a new, permanent account at Site B. 


The configuration instructions, starting in “Prerequisites” on page 431, use the Login method for the 
SAML 2.0 and Liberty protocols and Mapped Attributes method for the SAML 1.1 protocol. 


The instruction for setting up a trusted relationship between two Access Manager Identity Servers 
have been divided as follows: 


¢ “Prerequisites” on page 431 
¢ “Establishing Trust between Providers” on page 432 
¢ “Configuring SAML 1.1 for Account Federation” on page 438 


Prerequisites 


O Abasic Access Manager configuration with Identity Server and Access Gateway configured for 
SSL. 


This can be the one you set up using the instructions in either Chapter 3, “Setting Up a Basic 
Access Manager Configuration,” on page 57 or Chapter 3.12, “Sample Configuration for 
Protecting an Application Through Access Manager,” on page 227. For SSL configuration, see 
Chapter 17.1, “Enabling SSL Communication,” on page 977. 
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Identity Server from this configuration becomes Site B in Figure 5-7. 


O Asecond Identity Server with a basic configuration, an LDAP user store, and SSL. This Identity 
Server is configured to be Site Ain Figure 5-7. 


O Time synchronization must be set up for all the machines, or authentication can fail if assertions 
expire before they can be used. 


O ADNS server must be configured to resolve the DNS names of Site A, Site B, and Access 
Gateways. 


O (Recommended) Logging has been enabled on Identity Servers of Site A and Site B. See 
Section 21.3.1, “Configuring Logging for Identity Server,” on page 1038. Make sure that you 
enable at least application and protocol (Liberty, SAML 1, or SAML 2.0) logging at an Info level or 
higher. 


Establishing Trust between Providers 
To set up this very basic example of federation, complete the following tasks. 


¢ “Configuring Site A to Trust Site B as a Service Provider’ on page 432 
e “Configuring Site B to Trust Site A as an Identity Provider” on page 433 
e “Verifying the Trust Relationship” on page 435 

¢ “Configuring User Authentication” on page 436 


Configuring Site A to Trust Site B as a Service Provider 
To establish trust between Site A and Site B, you must perform two tasks: 
+ The providers must trust the certificates of each other so you need to import the trusted root 
certificate of Site B to Site A. 
+ You must also import the metadata of Site B to Site A. The metadata allows Site A to verify that 
Site B is truly Site B when Site B sends a request to Site A. 
The following instructions explain how to import the certificate and the metadata: 


1 Log in to Administration Console for Site A. 


The configuration for Site A can be created in the same Administration Console as Site B; it 
cannot be configured to be a cluster member of Site B. 


2 Import the trusted root certificate of Site B into the NIDP trust store of Site A: 
2a Click Devices > Identity Servers > Edit > Security > NIDP Trust Store. 
2b In the Trusted Roots section, click Auto-Import From Server, then fill the following fields: 
Server IPIDNS: Specify the IP address or DNS name of Site B. For Site B in Figure 5-7 
specify the following: 


idp.siteb.novell.com 


Server Port: Specify 8443. 
2c Click OK, then specify an alias for the certificate (for example, SiteB). 


You will get two certificate options: Root CA Certificate andServer certificate. We 
recommend you to select Root CA Certificate. 


2d Examine the trusted root that is selected for you. 


If the trusted root is part of a chain, make sure you select the parent and all intermediate 
trusted roots. 
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2e Click OK. 
The trusted root certificate of Site B is added to the NIDP trust store. 
2f Click Close. 
2g Click Devices > Identity Servers, then update Identity Server. 
Wait for the health status to return to green. 
3 Configure a service provider for Site A: 
3a Click Identity Servers > Edit > Liberty [or SAML 2.0 or SAML 1.1]. 
3b Click New, select Service Provider, then fill the following fields: 


Name: Specify a name for the provider. If you plan on configuring more than one protocol, 
include the protocol as part of the name, such as, SiteB_Liberty 


Metadata URL: Specify the URL of the Liberty metadata on Site B. For Site B in Figure 5-7, 
specify the following: 
http://idp.siteb.novell.com:8080/nidp/idff/metadata 


This example uses port 8080 to avoid any potential certificate problems that occur when 
Identity Server and Administration Console are installed on separate machines. 


SAML 2.0: If you are using SAML 2.0, the metadata path is /nidp/sam12/metadata. For 
Site B in Figure 5-7, specify the following for SAML 2.0: 
http://idp.siteb.novell.com:8080/nidp/sam12/metadata 


SAML 1.1: If you are using SAML 1.1, the metadata path is /nidp/saml/metadata. For 
Site B in Figure 5-7, specify the following for SAML 1.1: 


http://idp.siteb.novell.com:8080/nidp/saml/metadata 


3c Click Next > Finish > OK. 
3d Update Identity Server. 
Wait for the health status to return to green. 
4 Continue with “Configuring Site B to Trust Site A as an Identity Provider” on page 433. 


Configuring Site B to Trust Site A as an Identity Provider 


The following instructions explain how to import the trusted root certificate and metadata of Site A into 
the configuration for Site B. 
1 Log in to Administration Console for Site B. 


The configuration of Site B can be created in the same Administration Console as Site A; it 
cannot be configured to be a cluster member of Site A. 


2 Import the trusted root certificate of Site A into the NIDP trust store of Site B. 
2a Click Devices > Identity Servers > Edit > Security > NIDP Trust Store. 
2b In the Trusted Roots section, click Auto-lmport From Server, then fill the following fields: 
Server IPIDNS: Specify the IP address or DNS name of Site A. For Site A in Figure 5-7, 
specify the following: 


idp.sitea.novell.com 


Server Port: Specify 8443. 
2c Click OK, then specify an alias for the certificate (for example, SiteA). 
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2d 


2e 


2f 
2g 


You will get two certificate options: Root CA Certificate andServer certificate. We 
recommend you to select Root CA Certificate. 


Examine the trusted root that is selected for you. 


If the trusted root is part of a chain, make sure you select the parent and all intermediate 
trusted roots. 


Click OK. 

The trusted root certificate of Site A is added to the NIDP trust store. 
Click Close. 

Click Identity Servers > Update > OK. 

Wait for the health status to return to green. 


3 Configure an identity provider for Site B. 


3a 
3b 


3c 
3d 


Click Identity Servers > Edit > Liberty [or SAML 2.0 or SAML 1.1]. 
Click New, select Identity Provider, then fill the following fields: 


Name: Specify a name for the provider. If you plan on configuring more than one protocol, 
include the protocol as part of the name, such as SiteA_Liberty 


Metadata URL: Specify the URL of the Liberty metadata on Site A. For Site A in Figure 5-7, 
specify the following: 

http://idp.sitea.novell.com:8080/nidp/idff/metadata 

This example uses port 8080 to avoid any potential certificate problems that occur when 
Identity Server and Administration Console are installed on separate machines. 

SAML 2.0: If you are using SAML 2.0, the metadata path is /nidp/sam12/metadata. For 
Site Ain Figure 5-7, specify the following for SAML 2.0: 
http://idp.sitea.novell.com:8080/nidp/sam12/metadata 


SAML 1.1: If you are using SAML 1.1, the metadata path is /nidp/saml1/metadata. For 
Site B in Figure 5-7, specify the following for SAML 1.1: 


http://idp.siteb.novell.com:8080/nidp/saml/metadata 


Click Next. 
To configure an authentication card, fill in the following: 


ID: (Optional) Specify an alphanumeric number that identifies the card. If you need to 
reference this card outside of Administration Console, you need to specify a value here. If 
you do not assign a value, Identity Server creates one for its internal use. 


Text: Specify the text that is displayed on the card to the user 


Image: Specify the image to be displayed on the card. Select the image from the drop down 
list. To add an image to the list, click Select local image. 


Login URL: (Conditional) If you are configuring an authentication card for SAML 1.1, 
specify an Intersite Transfer Service URL. For Figure 5-6 on page 429, specify the following 
value: 


https://idp.sitea.novell.com:8443/nidp/saml/idpsend?P1ID=https:// 
idp.siteb.novell.com:8443/nidp/saml/metadata&TARGET=https:// 
idp.siteb.novell.com:8443/nidp/app 


For more information, see “Specifying the Intersite Transfer Service URL for the Login URL 
Option” on page 196. 
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Show Card: Determine whether the card is shown to the user. If this option is not selected, 
the card is only used when a service provider makes a request for the card. For this 
scenario, select this option. 


Passive Authentication Only: Do not select this option. 
3e Click Finish > OK. 
3f Update Identity Server. 
Wait for the health status to return to green. 
4 Continue with one of the following: 


¢ If you are using Liberty or SAML 2.0, continue with “Verifying the Trust Relationship” on 
page 435. 


¢ If you are using SAML 1.1, continue with “Configuring SAML 1.1 for Account Federation” on 
page 438. 


Verifying the Trust Relationship 


Before continuing with federation configuration, you need to verify that Site A and Site B trust each 
other. 


1 To test the trusted relationship, log in to the user portal of Site B. For Site B in Figure 5-7, specify 
the following: 


https://idp.siteb.novell.com:8443/nidp/app 


In this configuration, the customizable image was used for the Liberty authentication card. 
2 Click the menu, then click Liberty (or SAML2) authentication card. 
You are directed to Site A for login, with the default card selected for you. 


E] NetlQ Access Manager 


Authentication 


Password: | 


3 Enter the credentials for a user from Site A. 
The Federation consent prompt appears. 


NOTE: To disable this prompt, add the following parameter in the web. xml file under the 
IdapLoadThreshold context parameter: 


<context -param><param-name>federationConsent</param-name><param-value>true</ 
param-value></context-param> 


Linux: /opt/novell/nids/1ib/webapp/WEB- INF/web. xml 
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Windows: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEBINF\web. xml 


4 Click Yes. 
You are returned to the login page for Site B. 
5 Enter the credentials of a user from Site B that you want to federate with the user from Site A. 


These two accounts are now federated. You can enter the URL to the user portal on Site A or 
Site B, and you are granted access without logging in again. 


If you log out and log back in, the accounts are still federated, but you might be prompted for 
login credentials as you access resources on Site A and Site B. To enable a single sign-on 
experience, Identity Server at Site A, Identity Server at Site B, and the protected resources of 
Access Gateways must be configured to share a contract. 


6 To enable a single sign-on experience, continue with “Configuring User Authentication” on 
page 436. 


Configuring User Authentication 


The following instructions describe one way to enable single sign-on to Identity Servers and Access 
Gateways in Figure 5-6 on page 429. It explains how to configure all sites to use the same contract. 
The instructions explain the following tasks: 

¢ Selecting the contract for federation 

+ Configuring the contract at Site B to allow authentication at Site A 

¢ Configuring Site A so its contract can satisfy the requirements of the contract at Site B 

¢ Configuring Site A and Site B to use this contract as their default contract 


To configure the contracts: 


1 Log in to Administration Console for Site B. 
2 Configure the authentication request: 


2a Click Devices > Identity Servers > Edit > Liberty [or SAML 2.0] > [Name of Identity 
Provider] > Authentication Card > Authentication Request. 


2b (Liberty) Verify the settings of the following fields: 


Allow federation: Make sure this option is selected. If this option is not selected, users 
cannot federate their accounts at Site A with an account at Site B. 


After authentication: Make sure this option is selected. Enabling this option assumes that 
a user account exists at the service provider and that the account can be associated with a 
user’s account at the identity provider. 


During authentication: Make sure this option is selected. Enabling this option allows 
federation to occur when the user selects the authentication card of the identity provider. 


2c (SAML 2.0) Verify the settings of the following fields: 
Persistent: Select this option to set up a persistent relationship between the two accounts. 


After authentication: Make sure this option is selected. Enabling this option assumes that 
a user account exists at the service provider and that the account can be associated with a 
user’s account at the identity provider after authentication. 


During authentication: Make sure this option is selected. Enabling this option allows 
federation to occur when the user selects the authentication card of the identity provider. 


2d For Requested By, select Use Contracts. 
2e (SAML 2.0) For Context Comparison, accept the default value of Exact. 


Configuring Authentication 


3 


4 


o ON Oo 


2f In the Authentication contracts section, select the name of the contract used by the 
protected resources and move it to the Contracts section. 


If the contract you require is not in the list, it has not been configured for federation. See 
step 3. 


2g Click OK, then update Identity Server configuration. 
(Conditional) Configure the contract at Site B to allow federation: 
3a Click Identity Servers > Edit > Local > Contracts. 


3b Record the URI for the contract you are using. This URI needs to exist as a contract on Site 
A. The name of the contract can be different at each site, but the URI must be the same. 


NOTE: If site A only understands authentication class or type, select Use Types in the 
Requested By field and specify the authentication class in the Allowable Class field. Record 
the allowable class for the contract you are using. This allowable class must exist as a 
contract on site B. The name of the contract can be different at each site, but the allowable 
class must be the same. 


3c Click the name of the contract. 

3d Make sure the Satisfiable by External Provider option is selected. 

3e Click OK twice, then update Identity Server if you made any changes. 
3 


If Site A is configured as a SAML 2.0 identity provider, move the contract(s) from the Available 
contracts list to the Satisfies contract list. 


=> 


Return to Step 2 to select the contract. 


This will automatically redirect the authentication request from Site B to Site A when this contract 
is executed. Note that you can have multiple contracts in the Satisfies contract list. 


Verify that Site A contains the same contract:. 
5a Log in to Administration Console for Site A. 
5b Click Identity Servers > Edit > Local > Contracts. 
5c Match the URI from step 3b to a contract. 


NOTE: Match the allowable class if you have selected Use Types in the Requested By field 
at site B. 


If such a contract does not exist, you need to create it. For help, see Section 5.1.4, 
“Configuring Authentication Contracts,” on page 379. 


5d Click OK. 

In Administration Console for Site A, click Identity Servers > Edit > Local > Defaults. 
For the Authentication Contract, select the name of the contract from step 5c. 
(Conditional) If you have multiple user stores, set the default contract for each user store. 
Click OK, then update Identity Server. 

Test the configuration: 
10a Enter the URL to the user portal of Site B. 
10b Click the federated login link to Site A. 
10c Enter the credentials for Site A and log in. 
10d Enter the URL for a protected resource at Site B. 

You are granted access without being prompted for credentials. 
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11 If you want to allow federated users to log in at Site A rather than using the card at Site B to 
redirect them to Site A, complete the following tasks: 


11a In Administration Console for Site B, click Devices > Identity Servers > Edit > Local > 
Defaults. 


14b For the Authentication Contract, select the name of the contract whose URI matches the 
URI of the contract used by Site A. 


11c Click Liberty [or SAML 2.0] > [Name of Identity Provider] > Authentication Card > 
Authentication Request. 


11d In the Options section, enable the Use automatic introduction option. 


This enables single sign-on to Site B when the user has already federated the accounts at 
the two sites. 


11e Click OK, then update Identity Server. 


11f To test single sign-on, log in to the user portal on Site A, then enter a URL for a protected 
resource at Site B. 


Configuring SAML 1.1 for Account Federation 


SAML 1.1 does not support user-controlled federation, but you can configure it so that accounts that 
match are automatically federated. The Liberty and SAML 2.0 protocols allow users to federate 
accounts without sharing any common attributes, but the SAML 1.1 protocol requires that the user 
accounts need to share some common attributes for SAML 1.1 to match them and allow federation. 

+ “Configuring User Account Matching” on page 438 

¢ “Configuring the Default Contract for Single Sign-On” on page 440 

¢ “Verifying the Trust Relationship with SAML 1.1” on page 440 


Configuring User Account Matching 


When federating with SAML 1.1, the security of a user matching method depends upon the accuracy 
of the mapping. You need to select an attribute or attributes that uniquely identify the user at both Site 
A and Site B. The attributes must identify only one user at Site A and match only one user at Site B. If 
the attributes match multiple users, you have a security problem, 


The following steps use the e-mail address of the user and the LDAP mail attribute to set up a 
matching rule that matches one user account at Site A with one user account at Site B. To securely 
use such a matching rule, you need to have a rule in place at both Site A and Site B to ensure that all 
users have unique e-mail addresses. 


Configuring Site B for User Account Matching 
1 In Administration Console of Site B, click Devices > Identity Servers > Servers > Edit > SAML 
1.1 > [Identity Provider] > User Identification. 
2 For the Satisfies contract option, select the contract that you want to use for single sign-on. 
For this example, select Secure Name/Password-Form. 
3 Select Attribute matching. 


The Prompt for password on successful match option is automatically selected. Leave this 
option enabled. 


4 Click the Define Attribute Matching Settings icon. 
5 Move the user store that you want to search for the attribute to the User stores list. 
6 For the User Matching Expression, select New User Matching Expression. 
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7 Specify a name for the matching expression, such as email. 


8 In Logic Group 1, click the Add Attributes icon, select Ldap Attribute:mail [LDAP Attribute 
Profile], then click OK. 


The form allows you to create a very complex set of matching rules, with multiple conditions. 
This example uses one attribute, the simplest form of a matching expression. 


9 Click Finish, then select your matching expression for the User Matching Expression. 
10 Click OK. 
11 Click OK twice, then update Identity Server. 
12 Continue with “Configuring the Attribute for Sharing” on page 439. 
Configuring the Attribute for Sharing 
1 In Administration Console of the Site B (the service provider), click Devices > Identity Servers > 
Shared Settings. 
2 Click Attribute Sets, then click New. 
3 Specify a Set Name, such as email, then click Next. 
4 Click New, then fill the Add Attribute Mapping options: 
Local attribute: Select Ldap Attribute:mail [LDAP Attribute Profile]. 


Remote attribute: Specify a name, such as email. Make sure you use the same remote name in 
the mapping for both Site B and Site A. 


Leave the other options set to their default values. 
5 Click OK, then click Finish. 

Your newly created attribute mapping appears in the list of Attribute Sets. 
6 Repeat step1 through step 5 for Site A (the identity provider). 

If Site A and Site B are imported into the same Administration Console, skip this step. 
7 Continue with “Configuring the Providers to Use the Shared Attribute” on page 439. 


Configuring the Providers to Use the Shared Attribute 


You need to configure Site A to send the shared attribute with the authentication credentials, and you 
need to configure Site B to process the shared attribute that is included with the authentication 
credentials. 


1 In Administration Console for Site B, click Devices > Identity Servers > Edit > SAML 1.1 > [Name 
of Identity Provider] > Attributes. 


2 For the Attribute set, select the set name you created in “Configuring the Attribute for Sharing” 
on page 439. 


3 Move the email attribute so that it is obtained at authentication. 
4 Click OK twice, then update Identity Server. 


5 In Administration Console for Site A, click Devices > Identity Servers > Edit > SAML 1.1 > [Name 
of Service Provider] > Attributes. 


6 For the Attribute set, select the set name you created in “Configuring the Attribute for Sharing” 
on page 439. 


7 Move the email attribute so that it is sent with authentication. 
8 Click OK twice, then update Identity Server. 
9 Continue with “Configuring the Default Contract for Single Sign-On” on page 440 


Configuring Authentication 439 


Configuring the Default Contract for Single Sign-On 


Identity Servers at Site A and Site B need to use the contract you specified in your user matching 
expression to be the default contract for Site A, Site B, and the protected resources of Access 
Gateway. 


For the user matching expression contract, see step 2 in “Configuring Site B for User Account 
Matching” on page 438. 


To configure the default contracts for Site A and Site B: 


1 In Administration Console for Site B, click Devices > Identity Servers > Edit > Local > Defaults. 


2 For the Authentication Contract, select the name of the contract used by the user matching 
expression. 


3 Click OK, then update Identity Server. 
4 For Site A, repeat step 1 through step 3. 
5 For Access Gateway, review the contracts you have assigned to the protected resources: 


5a In Administration Console for Site B, click Devices > Access Gateways > Edit > [Name of 
Reverse Proxy] > [Name of Proxy Service] > Protected Resources. 


5b For single sign-on, change the contract to match the contract for the user matching 
expression. 


5c (Conditional) If you have multiple reverse proxies and proxy services, verify the contracts on 
all protected services that you want enabled for single sign-on. 


5d Click OK to save your changes, then update Access Gateway. 
6 Continue with “Verifying the Trust Relationship with SAML 1.1” on page 440. 


Verifying the Trust Relationship with SAML 1.1 


1 To test the trusted relationship, enter the URL for the user portal of Site B. For Site B in Figure 5- 
7, you would specify the following: 


https://idp.siteb.novell.com:8443/nidp/app 


Use the scroll bar to see all available cards. 
2 Click the menu then click card you have configured for SAML 1.1 authentication. 
You are directed to Site A for login. 
3 Enter the credentials for Site A. 
4 Enter the password for the user at Site B. 
You are directed to the target page specified in the Login URL of the authentication card. 


If you disabled the Prompt for password on successful match option on the User Identification 
page, the accounts are mapped without any user interaction. 


5 (Conditional) If you receive an error, try one of the following: 


+ If you are not redirected to the target URL on Site B, verify the value you enter for the Login 
URL option. See Step 3d on page 434. 


+ If you receive an authentication error at Site B, verify the user matching setup. See 
“Configuring User Account Matching” on page 438. 


+ |f you have enabled logging, open the logging file (catalina.out or stdout.log) and 
search for the error string. There must be additional information about the cause of the error 
in the error string entry as well as log entries before the error sting. 
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6 (Optional) If your protected resources on Site A and Site B use the same contract, enter the 
URLs of these resources. 


You are granted access without entering any additional credentials. 


Sharing Roles 


When two Identity Servers are configured to trust each other, one as an identity provider and the 
other as a service provider, they can be configured so that roles are shared. The following instructions 
are written for when both the identity provider and the service provider are Access Manager Identity 
Servers. If you are using a third-party identity or service providers, you need to modify the 
instructions. 


Figure 5-8 illustrates a configuration where Identity Server of Site Ais acting as an identity provider 
for Site B. When you configure Identity Servers correctly, Access Gateway can use the roles defined 
for the users of Site A in its policies. 


Figure 5-8 Two Federated Identity Servers 
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URL: https://provo.novell.com/bugz 


Access Gateway 


The key to sharing roles is to set up the configuration so that the SAML assertion that the identity 
provider (Site A) sends to the service provider (Site B) contains the roles that the user has been 
assigned. Site B evaluates the roles and assigns them to the federated users at Site B. Access 
Gateway can use these roles in its policy evaluations, and grant or deny access based on the 
assigned roles. 


For example, when user tsmith authenticates to Site A, tsmith is assigned the role of doc. Tom, a user 
at Site B, is federated with the tsmith user. The doc role is shared with Site B, and Site B contains a 
policy that assigns users with the shared doc role to the tester role. Access Gateway is configured 
with an Authorization policy that grants access to a resource when the requester is assigned the 
tester role. However, Tom does not have the qualifications at Site B to be assigned the tester role. 
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In this scenario, when Tom requests access to the protected resource at Site B, a login page with a 
federated link to Site A is displayed. If Tom selects to log in to Site A, Site A assigns him to the doc 
role. The doc role is sent with tsmith’s authentication credentials to Site B. Site B evaluates the 
credentials and assigns Tom to the tester role because the following conditions are met: 

+ Tom is federated with tsmith. 

¢ tsmith was assigned the doc role. 

+ The shared role and tester policies on Site B qualify the user to be assigned the tester role. 


When Access Gateway evaluates the credentials of Tom, Tom is granted access to the protected 
resource because he now has the tester role. 


This section describes how to set up such a configuration. It assumes that the following have already 
been done: 


+ The trusted relationship between the identity provider and service provider is set up. For 
configuration instructions, see “Establishing Trust between Providers” on page 432. 


+ The following policies have been created: the doc role policy at Site A, the tester role policy at 
Site B, and the Authorization policy (that uses the tester role) for Access Gateway. For 
information about creating a Role policy, see Chapter 8.2, “Role Policies,” on page 721, and for 
the Authorization policy, see “Assigning an Authorization Policy to a Protected Resource” on 
page 133. The following instructions explain how to set up the shared policy. 


This section explains how to configure Site A and Site B so that Site A shares its roles with Site B. 


¢ “Configuring Role Sharing” on page 442 
¢ “Verifying the Configuration” on page 445 


Configuring Role Sharing 


There are three major tasks for configuring role sharing. You need to configure a shared attribute for 
transferring the roles. You need to configure the identity provider and the service provider so that the 
role assignments can be added to the attribute and retrieved from the attribute. Finally, you need to 
create a shared Role policy for each role sent to the service provider. This policy defines how the role 
must be processed. 


The following sections describe these configuration tasks: 


¢ “Defining a Shared Attribute Set” on page 442 
e “Obtaining the Role Assignments” on page 443 
¢ “Configuring Policies to Process Received Roles” on page 443 


Defining a Shared Attribute Set 
1 In Administration Console of the Site A (the identity provider), click Devices > Identity Servers > 
Shared Settings. 
2 Click Attribute Sets, then New. 
3 Specify a Set Name, such as role_sharing, then click Next. 
4 Click New and fill the Add Attribute Mapping options: 
Local attribute: Select All Roles. 


Remote attribute: Specify a name, such as roles. Make sure you use the same remote name in 
the mapping for both the identity provider and the service provider. 


Leave the other options set to their default values. 
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5 Click OK, then click Finish. 
Your newly created attribute mapping appears in the list of Attribute Sets. 
6 Repeat Step 1 through Step 5 on Site B (the service provider). 
7 Continue with “Obtaining the Role Assignments” on page 443. 
Obtaining the Role Assignments 
1 To export the roles from the identity provider, log in to Administration Console for the identity 
provider. (In Figure 5-8, this is Site A.) 
1a Click Devices > Identity Servers > Edit > Liberty > [Name of Service Provider] > Attributes. 


If you are using SAML 2.0 or SAML 1.1 protocol, the steps are the same. You just need to 
click the appropriate tab after clicking Edit. The path is the same for these protocols. 


1b Select the attribute set you created, then move All Roles so this attribute is sent with 
authentication. 


1c Click OK. 
1d Update Identity Server of Site A. 


2 To import the roles from the identity provider to the service provider, log in to Administration 
Console for the service provider. (In Figure Figure 5-8, this is Site B.) 


2a Click Devices > Identity Servers > Edit > Liberty > [Name of Identity Provider] > > 
Attributes. 


2b Select the attribute set you created, then move All Roles so this attribute is obtained with 
authentication. 


2c Click OK. 
2d Update Identity Server of Site B. 
2e Continue with “Configuring Policies to Process Received Roles” on page 443. 


Configuring Policies to Process Received Roles 


For each role that is sent from Site A, you need to create a Role policy that specifies the role that 
must be activated on Site B. For example, suppose the tsmith user from Site A is assigned the doc 
role at authentication. You can create a Role policy on Site B that assigns the tester role to anyone 
with the doc role from Site A. 

Log in to Administration Console for Site B. 

Click Policies > Policies > New. 

Specify a name for the policy, select Identity Server: Roles for the type, then click OK. 

In the Condition Group 1 section, click New, then select Roles from Identity Provider. 


ao Aà WN PF 


(Conditional) If you have federated with more than one identity provider, select the provider. If 
you have federated with only one identity provider, the provider is selected for you. 


In this example, you have federated with only the identity provider at Site A, and it is selected for 
you. 


6 For the value, select Data Entry Field, then specify the name of a role that is assigned by Site A, 
for example doc. 


If you leave Mode set to Case Sensitive, make sure you specify the case correctly. 
7 Inthe Actions section, specify the role to activate on Site B for the role received from Site A. 
Your policy must look similar to the following: 
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Edit Rule: receive_roles - Rule 1 


Type: Identity Server: Roles 
Description: 
Priority: 1 5 
Conditions Condition structure: | AND Conditions, OR groups Y 


Condition Group 1 


Roles from Identity Provider: E 


Comparison: String: Equals Y 
Mode: Case Sensitive 


Value: Data Entry Field w 


Result on Condition Error; False w 


Append New Group | 


Actions 


New w 


Do Activate Role 
tester 


Changes made on this panel must be applied from the Policies Panel. 


OK Cancel 


8 Click OK twice, then click Apply Changes. 

9 To enable the role for Identity Server, click Identity Servers > Edit > Roles. 
10 Select the role, then click Enable. 
11 (Optional) Repeat Step 2 through Step 10 for other roles assigned at Site A. 


If you have other Role policies at Site A, you need to set up Role policies at Site B to have the 
roles activated. For example, if Site Ahad a Tester Role policy and you wanted users assigned 
to the Tester Role policy to also be assigned to the Tester Role policy at Site B, you could create 
a separate policy for this activation, or you could add an Or condition group with a value field of 
tester to the policy in Step 7. The policy would assign federated users who belonged to the doc 
or tester roles at Site A, to the tester role at Site B. 


12 To test role sharing: 


12a Enter the URL of a protected resource that requires a role for access. For the policy above, 
it would be a resource requiring the tester role. 


12b Click the federated link to Site A. 
12c Log in with the credentials of a user who is assigned the doc role. 


You are granted access to the resource. If you are denied access, continue with “Verifying 
the Configuration” on page 445 to discover the problem. 


Configuring Authentication 


Verifying the Configuration 


This section traces the role assignment from Identity Server that assigns it to the user, through 
Identity Server that receives the roles with the user’s authentication assertion, to the policy 
evaluation. If you are having trouble, this must help you determine the source of the problem. 


The following procedures refer to the configuration displayed in Figure 5-8, “Two Federated Identity 
Servers,” on page 441. Atsmith user from Site A, who is assigned the doc role, is federated with a 
Tom user at Site B. Site B does not assign Tom the tester role. The Web server has been configured 
to protect the bugz site, which requires the tester role. 


To verify the configuration: 
1 Make sure policy logging is enabled on the identity provider and the service provider. Make sure 
that you enable at least Application logging at an Info level. 


For configuration procedures, see Section 21.3.1, “Configuring Logging for Identity Server,” on 
page 1038. 


You can access log files for downloading and viewing by clicking Auditing > General Logging. 
2 Have a user access a resource that is protected by a policy requiring a role from Site A. 


For this trace, the tsmith user from Site A requests access to the bugz page. The user uses the 
federated link and logs in with the credentials of the tsmith user. 


3 Verify that Site A is assigning the user the role. 


3a View the catalina. out file (Linux) or the stdout . log file (Windows) of Identity Server at 
Site A. 


3b Search for the name of the role. You must find a line similar to the following: 


<amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105013: 
AMDEVICEID#C5F467BA50BOO9AC: AMAUTHID#DEEF6BEC3655DEB71CA56832DDDF866E : 
Authenticated user cn=tsmith,o=novell in User Store sitea-nids-user-store 
with roles doc,authenticated. </amLogEntry> 


If the role you need is not listed, look at the policy evaluation trace to discover why the user 
has not been assigned the role. For more information about how to understand role traces, 
see “Role Assignment Traces” on page 1281. 


4 Verify that Site Ais sending an authentication assertion to Site B. 


In the catalina. out file (Linux) or the stdout .1og file (Windows) of Identity Server from Site A, 
look for lines similar to the following: 


<amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105018: 
AMDEVICEID#C5F467BA50BO09AC: AMAUTHID#DEEF6BEC3655DEB71CA56832DDDF866E: 
Responding to AuthnRequest with artifact 

AAPLSCVpfv3ha9Mpn+cUiCxXcf3D63scOQfscL5mZaaygHBKVOOh9aPSQ </amLogEntry> 


<amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105019: 
AMDEVICEID#C5F467BA50BO09AC: AMAUTHID#F8B1C147EB3DDEFE9A3DB0827BA8E4A3 : 
Sending AuthnResponse in response to artifact 

AAPLSCVpfv3ha9Mpn+cUiCXcf3D63scOQfscL5mZaaygHBKVOOh9aPSQ </amLogEntry> 


If you do not see these types of entries, verify that you have configured Site A to send the roles. 
See “Obtaining the Role Assignments” on page 443. 


5 Verify that Site B is receiving the SAML assertion with the roles. 


In the catalina. out file (Linux) or the stdout .1log file (Windows) of Identity Server from Site B, 
look for lines similar to the following: 
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<amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105020: 
AMDEVICEID#488475009C6D3DDF: AMAUTHID#OFBAOCF7E41E6C7F9121DABB918D34F4: 
Received and processing artifact from IDP - 

AAPLSCVpfv3ha9Mpnt+cUiCxXcf3D63scOQfscL5mZaaygHBKVOOh9aPSQ </amLogEntry> 


<amLogEntry> 2009-08-22T20:30:19Z INFO NIDS Application: AM#500105021: 
AMDEVICEID#488475009C6D3DDF: AMAUTHID#OFBAOCF7E41E6C7F9121DABB918D34F4: 
Sending artifact AAPLSCVpfv3ha9Mpn+cUiCxXcf3D63scOQfscL5mZaaygHBKVOOh9aPSQ to 
URL https://rholm. provo.novell.com:8443/nidp/idff/soap at IDP </amLogEntry> 


The artifact ID must be the same as the artifact ID in Step 4. 


If you do not see these types of entries, verify that you have configured Site B to receive the 
roles. See “Obtaining the Role Assignments” on page 443. 


Verify that Site B is evaluating the received role assignments and activating the roles. 


In the catalina. out file (Linux) or the stdout . log file (Windows) of Identity Server from Site B, 
search for a policy evaluation for RolesFromldentityProvider. You must find lines similar to the 
following: 


~~CO~1~RolesFromIdentityProvider (6670) :https://ipd.sitea.provo.novell.com: 
8443/nidp/idff/metadata: TESTER, DOC, AUTHENTICATED~com. novell.nxpe.condition. 
NxpeOperator@string-equals~(0@) :hidden-param:hidden-value:~~~True(69) 


~~PA~ActionID_1203705845727~~AddRole~tester~~~Success(0) 


<amLogEntry> 2009-08-22T20:30:20Z INFO NIDS Application: AM#500105013: 
AMDEVICEID#488475009C6D3DDF: AMAUTHID#OFBAOCF7E41E6C7F9121DABB918D34F4: 
Authenticated user cn=Tom,o=novell in User Store Internal with roles 
tester,authenticated. </amLogEntry> 


The policy evaluation shows that the condition evaluates to true and that the tester role is 
activated. Tom is the user that is federated with the tsmith user, and the entry shows that Tom 
has been assigned the tester role. 


If you do not see a policy evaluation for RolesFromldentityProvider, make sure you have created 
such a Role policy and that you have enabled it. See “Configuring Policies to Process Received 
Roles” on page 443. 


If the use has been assigned the correct role, the last step is to verify how the embedded service 
provider evaluated the policy protecting the resource. 


In the catatina.out file of the ipd-esp file for Access Gateway, search for lines similar to the 
following for the authorization policy trace: 
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<amLogEntry> 2009-08-22T20:30:20Z INFO NIDS Application: AM#501102050: 
AMDEVICEID#esp -2559E77C93738D15: AMAUTHID#BCF3CB40B51E8A0AF8582BEF762B4DDD: 
PolicyID#65LN2330-KN19-1L7M-176M-P942LMN6P832: NXPESID#1411: AGAuthorization 
Policy Trace: 

~~RL~1~~~~Rule Count: 2~~Success(0) 
~~RU~RuleID_1198874340999~Allow_Tester~DNF~~1:1~~Success(0) 
~~CS~1~~ANDs~~1~~True(69) 
~~C0O~1~CurrentRoles (6660) :no-param: TESTER, AUTHENTICATED~com. 
novell.nxpe.condition.NxpeOperator@string-substring~SelectedRole 

(6661) :hidden-param:hidden-value:~~~True(69) 

~~PA~1~~Permit Access~~~~Success(0) 
~~PC~1~~Document=(ou=xpem1PEP, ou=mastercdn, ou=ContentPublisher 

Container, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerCon 
tainer, o=novell: romaContentCollectionXMLDoc),Policy=(Allow_Tester),Rule=(1::Ru 
leID_1198874340999), Action=(Permit: :1)~~~~Success(0) 

</amLogEntry> 


If the PA line does not evaluate to Permit Access, then you need to review the Authorization 
policy and discover the conditions, other than the tester role, that must be met to permit access. 


Setting Up Federation with Third-Party Providers 


Setting up federation with providers other than Access Manager Identity Servers requires the same 
basic tasks as setting up federation with Access Manager Identity Servers, with some modifications. 


When you set up federation with identity providers and service providers that are controlled by a 
single company, you have access to Administration Consoles for both Identity Servers and know the 
admin credentials. When setting up federation with another company, additional steps are required. 


+ You need to negotiate with the other company and gain approval for federation because 
metadata must be shared and both sites require configuration. You need to negotiate a schedule 
for these configuration changes. 


+ The other site might not be using Access Manager for its identity or service provider. The basic 
tasks need to be modified to accommodate how that implementation shares metadata, 
authentication methods, and roles. 


+ Many SAML 1.1 providers do not support a metadata URL, and the data must be imported 
manually. 


For example, instead of sharing URLs that allow you to import metadata, you might need to 
share the actual metadata and paste it into the configuration. The Access Manager Identity 
Server validates the metadata of another identity provider or service provider; some 
implementations do not validate it. If Identity Server determines that the metadata is invalid, you 
need to negotiate with the provider to send you metadata that has been validated. 


¢ Most third-party providers do not support authentication cards and contracts. However, most do 
support either authentication types or authentication URIs. You can use either of these to map 
from their authentication procedure to an Identity Server authentication contract. 


For sample implementations with third-party providers that explain the modifications that were 
required to set up the federation, see the following: 


¢ “Integrating Novell's Access Manager with Shibboleth's IDP Server” (http:/Awww.novell.com/ 
communities/node/6943/integrating-novells-access-manager-shibboleths-idp-server) 


+ “Integrating Google Apps and Novell Access Manager using SAML2” (http://www.novell.com/ 
communities/node/8645/integrating-google-apps-and-novell-access-manager-using-saml2) 


¢ “SAML 1.1 with Concur” (http://www.novell.com/coolsolutions/appnote/19673.html) 
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Service Provider Brokering 


The Service Provider Brokering (SP Brokering) feature enables Identity Server to act as a federation 
gateway or a service provider broker. This federation gateway allows you to connect to different 
protocols such as Liberty, SAML 1.1, and SAML 2.0. You can use SP Brokering with the Intersite 
Transfer service of the identity provider. Intersite Transfer service enables authentication at a trusted 
service provider.SP Brokering helps companies establish trust between identity providers and their 
service providers that support different federation protocols. For example, an identity provider that 
supports SAML 2.0 can provide authentication to a Liberty or SAML 1.1 service provider by using SP 
broker. 


SP Brokering helps reduce the number of trust relationships between an identity provider and their 
service provider. For example, identity providers can now provide authentication to their service 
providers by establishing a single trust relationship instead of multiple trust relationships. Similarly, a 
service provider must establish a single trust relationship with SP Broker to receive authentication 
from several identity providers. 


You can control the authentication flow between several identity providers and service providers in a 
federation circle by allowing the administrator to configure policies that control Intersite Transfers. For 
example, an administrator can configure a policy with SP Broker that allows only certain users from 
an identity provider to be authenticated at a given service provider. 


An Intersite Transfer URL has the following format: https://<identity provider>/ 
idpsend?PID=<Service Provider ID>&TARGET=<final_destination_URL> 


This Intersite Transfer URL consists of three parts: 


¢ https://<identity provider>: The user can authenticate at the identity provider. 


¢ /idpsend?PID=<Service Provider ID>: Authentication occurs at the service provider 
represented by the service provider ID at the identity provider. 


¢ &TARGET=<final_destination_URL: The user is finally redirected to the specified target URL 
associated with the service provider. 


A Web page is created with many Intersite Transfer URLs for each combination of identity provider, 
service provider, and the target application. 


For more information about the Intersite Transfer Service, see Section 3.9.10, “Using the Intersite 
Transfer Service,” on page 194. 
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Originating IDP Allowed SP 


This following illustration explains the flow of providing access to the target URL by using SP 
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a n 


Web Page (User Portal): A Web page (user portal) is created with a list of URLs called Brokered 


© (4) 


URLs, which provide access to various target applications. 


Originating Identity Providers: The Originating Identity Provider is the identity provider with which 


the user credentials are stored for authentication. The Origin IDP must be configured as a Liberty/ 


SAML1.1/SAML2.0 trusted identity provider in the SP Broker. 


Federation Gateway or SP Broker: The Federation Gateway or SP Broker is a Access Manager 


identity provider that can be configured to control the authentication between several Origin IDPs and 


Allowed SPs in a federation circle. 


Allowed Service Provider: The Allowed SP is the service provider in which the SP Broker provides 
authentication. The allowed SP must be configured as a Liberty/SAML1.1/SAML2.0 trusted service 


provider on SP Broker. 


Target Application: The target application is the application running on a Web Sever that is 


protected by the service provider. 


Broker URL: A Broker URL is a specially designed Intersite Transfer URL, which consists of four 


parts. You can click the brokered URL, which results in the following: 


1. You must authenticate with the Originating IDP (https: //idp1.com/idpsend). 


2. The Origin IDP causes an authentication to occur at the SP Broker (?7PID=SPBroker). 
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3. The SP Broker causes an authentication to occur at the allowed SP (TARGET=https:// 
spbroker.com/idpsend?PID=SP1). 


4. You are redirected to the target application (7TARGET=TARGET1). 


SP Brokering requests are the Intersite Transfers resulting from brokered URLs processed on the SP 
Broker. The SP Broker can control the brokering requests before providing an authentication to the 
service provider. The SP Broker enforces the policies configured by the administrator by either 
causing the authentication at the service provider or by denying the request. 


The SP Broker provides the following options to configure policies that control SP brokering requests: 


1 Aset of SAML 1.1, SAML 2.0 and Liberty trusted identity providers and trusted service providers 
can be configured as a brokering group. The brokering request is allowed only if the Origin 
identity provider and Allowed service provider belong to the same brokering group. Brokering 
Request is not allowed from an Origin identity provider of one group to an Allowed service 
provider of another group. 


2 In a brokering group, a set of brokering rules can be configured that provides granular control on 
the brokering requests. For example, a brokering rule can be configured to deny a brokering 
request from an Origin identity provider to an Allowed service provider, if the user satisfies a 
certain condition at the SP Broker. 


SP brokering is enabled on Identity Server only if at least one brokering group is enabled. If an 
Intersite Transfer request is received with neither the origin identity provider nor the Allowed service 
provider in any of the brokering group, the request is treated as a regular Intersite Transfer and SP 
brokering controls are not applied. 


This chapter provides information about configuring the Access Manager SP Brokering 
functionalities, various deployment scenarios, and associated configuration details. 
¢ Section 5.2.2.1, “Configuring a SP Broker,” on page 450 
¢ Section 5.2.2.2, “Configuring a Brokering for Authorization of Service Providers,” on page 453 
¢ Section 5.2.2.3, “Creating and Viewing Brokering Groups,” on page 454 


¢ Section 5.2.2.4, “Generating the Brokering URLs by Using an ID and Target in the Intersite 
Transfer Service,” on page 460 


¢ Section 5.2.2.5, “Assigning The Local Roles Based On Remote Roles And Attributes,” on 
page 461 


¢ Section 5.2.2.6, “SP Brokering Example,” on page 462 


Configuring a SP Broker 


This section describes how to configure the origin identity provider to act as a SP Broker ora 
federation hub and also control authentications provided by the Origin identity providers to their 
Allowed service providers. 


Prerequisites 


1. Identify the Origin identity providers and their Allowed service providers. For example, Company 
1 establishes a business partnership with Partner 1, at which Company 1 users can access the 
application of Partner 1. In this case, identity provider at Company 1, is now the Origin identity 
provider and Allowed service provider is the service provider at Partner 1, and controls access to 
its applications. 


2. Identify the federation protocols supported by the Origin identity providers and their Allowed 
service providers. Access Manager Identity Provider supports SP brokering for SAML 2.0, 
Liberty, or SAML 1.1 federations. 
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3. Identify whether Persistent or Transient federations needs to be established between Company 
1 and Partner 1. For Persistent federation, the user that is authenticated at the Origin identity 
provider must be mapped to a valid user at their Allowed service provider. For Transient 
federation, the user is provided with a temporary identity at the Allowed service provider. 


Configuration Flow 


The following diagram depicts the various configuration steps involved in enabling the SP 
Brokering feature assuming SP Brokering is enabled between Company 1 and Partner 1: 


Partner 1 


a 


Allowed Application/ 


Service Provider WebServer 


(SP Broker) 
Novell Identity Server 


Step 1: Establish Federation at Origin Identity Providers to SP Broker 


1. The SP Broker must be configured as the service provider at origin identity provider of Company 
1. 


For more information, see “Creating a SAML 1.1 Service Provider” on page 507. 
If Access Manager identity provider is the Origin identity provider, refer. 


For more information, see “Creating a Trusted Service Provider” on page 183. 


Step 1a: Establish Federation at Allowed Service Providers to SP Broker 


The SP Broker must be configured as the identity provider at the allowed service provider of Partner 
1. 


For more information, see “Creating a Trusted Identity Provider’ on page 181. 
If Access Manager identity provider is the allowed service provider, refer. 


For more information, see “Creating a Trusted Service Provider” on page 183. 


NOTE: Step 1 must be repeated for each of the origin identity provider in the federation circle and 
step 1a must be repeated for each of the allowed service provider in the federation circle. 
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Step 2: Establish Federations at SP Broker for Origin Identity Providers and 
their Allowed Service Providers 


At the SP Broker, configure origin identity provider of Company 1 as the identity provider. The 
federation protocol (SAML 1.1/ SAML 2.0/ Liberty) and the federation type (Persistent or Transient) 
must match the federation protocol and federation type that is used for the respective origin identity 
provider in the step 1 above. 


For more information, see “Creating a SAML 1.1 Service Provider” on page 507, “Creating a Liberty 
Service Provider” on page 511, and “Creating a Trusted Service Provider” on page 183. 


Step 2a: 


At the SP Broker, configure the allowed service provider of Partner 1 as the service provider. The 

federation protocol (SAML 1.1/ SAML2.0/ Liberty) and the federation type (Persistent or Transient) 
must match the federation protocol and the federation type that is used for the respective allowed 

service provider in the Step1a above. 


For more information, see “Creating a Trusted Identity Provider’ on page 181. 


For more information, see “Creating a Trusted Service Provider” on page 183. 


NOTE: Step 2 must be repeated for each of the origin identity provider in the federation circle and 
Step 2a must be repeated for each of the allowed service provider in the federation circle. 


Step 3: Configure the Attribute to be Cached at the SP Broker (Optional) 


If the target applications require user information, then this information must be passed along with the 
authentication by the origin identity provider. At the SP Broker, these attributes that are received at 
the authentication must be cached and sent to the allowed service provider during authentication. 


For more information, see “Configuring the Attributes Obtained at Authentication” on page 187. 

For more information, see “Configuring the Attributes Sent with Authentication” on page 188. 

Step 4: Create Brokering Group for the Federation Circle with the Origin Identity 
Providers and their Allowed Service Providers 


Create a new brokering group in the SP Broker. Company 1 identity provider and Partner 1 service 
provider must be selected as the origin identity provider and their allowed service provider. 


For more information, see “Creating a Brokering Group” on page 455. 


The SP Brokering is enabled when at least one brokering group is enabled. Origin identity providers 
and their allowed service providers can either be added while creating the brokering group or added/ 
deleted by editing the brokering group. 


Step 5: Create Brokering Rules for the Brokering Group 


Create brokering rules that provide granular control on the brokering requests. For example, a 
brokering rule can be configured which can deny a brokering request from an origin identity provider 
to an Allowed service provider, if the user satisfies a certain role at the SP Broker. 


For more information, see “Configuring Brokering Rules” on page 456. 
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5.2.2.2 


To use roles in the brokering rules, identity role policies must be configured on Access Manager 
identity provider acting as an SP Broker. Roles can be associated for the user at the SP Broker 
according to the various parameters that include roles sent by the origin identity provider, attribute 
values sent from the identity provider. 


For more information, see Section 8.2.2, “Enabling Role-Based Access Control,” on page 725. 


Several rules can be configured for a brokering group. To help administrators understand how the 
rules are applied, a Rule Validation user interface is provided under each brokering group. 


For more information, see “Validating Brokering Rules” on page 459. 


Step 6: Create and Configure Brokering URLs 


The users at Company 1 are provided with a portal page containing URLs to access the applications 
at the service provider of Partner 1. These URLs are called Brokering URLs and are designed to pass 
through the SP Broker. The URLs consists of information that are embedded and a tool is provided to 
construct these URLs. The administrator can create URLs from a given origin identity provider to their 
allowed service provider to access a given target application specified by a target URL. The URLs 
constructed are placed in the users’ portal page. 


For more information, see “Constructing Brokering URLs” on page 458. 


Configuring a Brokering for Authorization of Service Providers 


Authorization rules for authorizing service provider requests must be configured from the Access 
Manager Brokering page. To configure authorization policy, configure the broker rule policy. Ensure 
that the service providers are configured to the local Identity Server that will be evaluated during 
authorization. Figure 5-9 on page 454 displays the sample configuration. 


Configuring Authentication 453 


Figure 5-9 SAMI2 Service Provider Initiated Authorization Rule Configuration 


Edit the Brokering Rule 


Rule Name rule 
Rule Priority 1 ~v 


Trusted Providers 
m Origin IDP Allowed SP 
» Any IDP © Any SP 
@ The following: © The following: 
Allowed IDPs Available Trusted IDPs in the Group Allowed SPs Available Trusted SPs in the Group 
Local IDP a Nam-ServiceProvidel + ^ 


Em 


5 
Role Conditions 


New | Delete 
[| Condition 
E] brokerrule 


Action 


| © Permit @ Deny | 


5.2.2.3 Creating and Viewing Brokering Groups 


Identity Server cluster configuration provides a Brokering tab that you can use to configure the 
groups and generate brokered URLs. 
1 Click Devices > Identity Servers > Brokering. 


2 The Brokering tab allows you to create new Groups as well as display the configured 
Groups. The Display Brokering Groups page displays the list of groups configured. 


You can also create, delete, enable, and disable the brokering group on this page. 
3 The Display Brokering Groups page displays the following information for each group: 


Group Name: Specifies a unique name to identify the group. When you click on the hyperlink, 
you can view the Group Details page, where the Group configuration such as name and list of 
Identity Providers and Service Providers can be modified. 


Enabled: A check mark indicates that brokering is enabled for the group by applying the 
configured rules. A blank means that brokering is disabled. 

Identity Providers: Display the total number of Liberty/SAML1.1/SAML2 IDPs assigned to this 
group. 

Service Providers: Display the total number of Liberty/SAML1.1/SAML2 SPs assigned to this 
group. 
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Brokering Rules: If the rules are not configured, then “No Rules Config” is displayed. The 
default rule allows for brokering between any IDP to any SP in the group. If new rules are 
configured, then the first rule name is displayed along with the count of total rules. 

¢ “Creating a Brokering Group” on page 455 

¢ “Configuring Trusted Identity Providers and Service Providers” on page 456 

¢ “Configuring Brokering Rules” on page 456 

¢ “Constructing Brokering URLs” on page 458 

èe “Validating Brokering Rules” on page 459 


Creating a Brokering Group 


When a brokering group is created while grouping the brokering feature, following rules are 
applicable: 


¢ Brokering is not allowed among different company groups. 
The brokering is not allowed between the logical customers of Company 1 Brokering Group and 
Company 2 Brokering Group. 

¢ Brokering is allowed among different partners of the company group. 


Brokering is allowed between the brokering groups of Company 1 Brokering Group and 
Company 2 Brokering Group. 


+ Role based brokering is allowed among Company 1 and Partner 1 logical customers. 
+ Role based brokering is allowed among Company 2 and Partner 2 logical customers. 
¢ Brokering is allowed among different partners based on roles and groups authentication of the 
company. 
To create a new broker group follow these steps: 


1 Click Devices > Identity Servers > Brokering. 

2 Click New. The Creating Brokering Group page displays. 

3 Perform the following actions in the fields: 
Display Name: Specify the brokering group display name. 
Selected IDPs: Select at least one trusted IDP using navigation button. 
Selected SPs: Select at least one trusted SP using navigation button. 


Available Trusted IDPs: Displays Liberty/SAML1.1/SAML2.0 trusted IDP configured on the 
given IDP cluster (idp_cluster1). 


Available Trusted SPs: Displays Liberty/SAML1.1/SAML2.0 Trusted Service Providers 
configured on the given Identity Provider Cluster (idp_cluster‘). 


4 Click Finish to complete creation of the brokering group creation. 
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Configuring Trusted Identity Providers and Service Providers 


You can configure the rules between the trusted identity providers and service providers by 
configuring rules, roles, and actions. You can view the configured rules, create new, delete the 
existing rule, edit the rules, enable and disable the configured rules. 


You can configure the service providers and identity providers for all of the protocols in Identity 
Server, which are configured in Identity Server cluster. Using the brokering group, you can view the 
list of available service providers and identity providers in the selection box. Using the arrow keys, 
configure the trusted identity providers and trusted service providers for the respective brokering 
group. 


1 Click Devices > Identity Servers > Brokering Group Name. The Configuration page displays the 
Trusted Providers, Brokering rules, Construct URL and Rule Validation tabs. 

2 Click Trusted Providers tab. 

3 Specify the display name and configure the brokering groups. 
Display Name: Specify the display name of the configuring brokering group. 


Select IDPs: Configure the selected identity providers using the arrow keys from the available 
trusted IDPs. 


Available Trusted IDPs: Configure the available trusted identity providers using the arrow keys 
from Selected Identity Providers selection box. 


Selected SPs: Configure the selected service providers using the arrow keys from the Available 
Trusted Service Providers selection box. 


Available Trusted SPs: Configure the available trusted service providers using the arrow keys 
from the Selected Service Providers selection box. 


4 Click OK to continue and the configured service providers and identity providers details are 
displayed in the Brokering page. 


5 Click Finish to complete the rules configuration for the brokering group. 
6 Click Apply to see the configuration changes. 


NOTE: When you log out from Access Gateway device, then the logout is not propagated on the 
other Identity Servers if you have SAML 1.1 as one of the trusted provider in the brokering group. 


Configuring Brokering Rules 
You can create, edit, delete, enable, and the disable brokering rules. 


1 Click Devices > Identity Servers > Brokering. 

2 Click the existing or newly created Brokering Group hyperlink. 

3 Click Rules. The Brokering Group Rules page is displayed. 
Name: Displays the rule name of the brokering group. 
Enabled: Displays the status of the brokering group rule. 
Identity Providers: Displays the number of identity providers configured to the brokering group. 
Service Providers: Displays the number of service providers configured to the brokering group. 
Priority: Displays the brokering group rule priority number. 
Actions: Displays the configured brokering group rule action status either as permit or deny. 


Role Conditions: Displays the brokering group role condition, such as manager and emplyee , 
configured on the rule page. 
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4 Click OK to continue and display the configured brokering group rule details on the Brokering 
Rules page. 


5 Click Apply to see the brokering rule configuration changes. 


Creating a Brokering Rule 
You can configure the rules to the created brokering groups. 


1 Click Devices > Identity Servers > Brokering. 
2 Click the existing or newly created Brokering Group hyperlink. 
3 Click Rules. The Creating Brokering Group page displays. 
Rule Name: Specify the name of the rule. 
Rule Priority: Select the rule priority from the drop-down list. 


NOTE: The default rule specified during creation of the group has a priority of 1. Additional rules 
can be added, and existing rules can be deleted or modified. You can use the Edit Rules Page to 
modify the priority of the rules. 


Origin IDP: Displays all Identity Servers or one or more Identity Servers that are available in the 
group. 


Allowed SP: Displays all service providers or one or more service providers that are available in 
the group. 

Role Conditions: Displays the brokering group role condition such as manager and employee, 
configured on the rule page. 


Actions: Select the Permit or Deny action radio button for the rule you configure to the brokering 
group. 


NOTE: By default, Access Manager allows any role. If you want to allow access to only particular 
roles, configure a permit condition for roles with higher priority and configure a deny condition in 
which no roles are defined with lower priority. 


4 Click Finish to complete configuration of rules for the brokering group. 
Deleting a Brokering Rule 


1 Click Devices > Identity Servers > Edit > Brokering > (Brokering Group in the Brokering Group 
list) > Rules. 


2 Select the check box of the brokering group rule you want to delete, then click Delete. A 
message is displayed as “Delete selected brokering rule(s)?”. 


3 Click OK to continue. 
Enabling a Brokering Rule 


1 Click Devices > Identity Servers > Edit > Brokering > (Brokering Group in the Brokering Group 
list) > Rules. 
2 Select the check box of the brokering group rule you want to enable. 


3 Click Enable.The selected brokering group is enabled. 
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Disabling a Brokering Rule 
1 Click Devices > Identity Servers > Edit > Brokering > (Brokering Group in the Brokering Group 
list) > Rules. 


2 Select the check box of the brokering group you want to disable from the brokering group rule 
configuration. 


3 Click Disable. The selected brokering group is disabled. 


Editing Brokering Rules 
You can edit the group rules in the Brokering page. 


1 Click Devices > Identity Servers > Edit > Brokering. 

2 Click the existing or newly created brokering group hyperlink. 

3 Click Rules tab. 

4 Click the Brokering Rules hyperlink to edit the information. The Edit Brokering Rule page 
displays the information. You can also edit the information. 


You can edit all the fields and modify the information about the Create Brokering Rule page. For more 
information about create brokering rule, see “Creating a Brokering Rule” on page 457 


Constructing Brokering URLs 


The Construct URL page helps you to create a URL, which you use in your application to navigate to 
your trusted partners. 


You can generate the URL according to the origin and allowed service provider Identity Servers. 


1 Click Devices > Identity Servers > Brokering. 
2 Click the existing or newly created brokering group hyperlink. 
3 Click Construct URL. 


IDP Type: Select the Identity Provider type from the drop-down list. The three types of IDP in the 
drop-down list are Local IDP, Access Manager IDP, and Other IDP. If you select Access Manager 
IDP as the IDP type, then you can select the Origin IDP from the drop-down list. If you select 
Other IDP as the IDP type, you can enter the Origin IDP URL and you can select the Origin IDP 
from the drop-down list. 


Origin IDP: The Origin identity providers are the trusted providers. The drop-down list displays 
all the trusted providers created for the specific Access Manager brokering group. Select the 
Origin IDP from the drop-down list. 


NOTE: If the Origin IDP drop-down list does not list any trusted providers, it is because a local 
Identity Server exists as a trusted provider. To resolve this, add another Identity Server to the 
Access Manager brokering group 


Origin IDP URL: If you select Other IDP as the IDP type, you can enter the Origin IDP URL 
manually. The <OriginIDPURL> represents (protocol :// domain : port / path ? querystring). 


Provider Parameter Name: If you select Other IDP as the IDP Type, you can enter the trusted 
provider parameter ID. For more information about Intersite Transfer Service target for a service 
provider, see “Configuring an Intersite Transfer Service Target for a Service Provider” on 

page 199 


Target Parameter Name: If you select Other IDP as the IDP type, you can enter the target 
provider parameter name manually. 
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Allowed SP: The allowed service providers are the selected service providers of the trusted 
roviders. The drop-down list displays all the service providers created for the specific brokering 
group. Select the service providers from the drop-down list. 


Target URL: Specify the target URL for the specific trusted providers and service provider pair. 
This URL will be appended to the login URL. Click Generate to generate the login URL 


Login URL: The login URL consists of Origin IDP URL and the target URL. 
4 Click Cancel to close the Construct URL page. 


Validating Brokering Rules 


The rule validation page helps you to validate the Origin identity providers and the allowed service 
provider rule according to the role associated with the respective trusted partners. 

1 Click Devices > Identity Servers > Brokering. 

2 Click on the existing or newly created brokering group hyperlink. 

3 Click the Rule Validation tab. 


Origin IDP: The Origin identity providers are the trusted providers. The drop-down list displays 
all the trusted providers created for the specific Access Manager brokering group. Select the 
Origin identity providers from the drop-down list. 


Allowed SP: The Allowed SPs are the selected SPs of the trusted providers. The drop-down list 
displays all the service providers created for the specific brokering group. Select the service 
providers from the drop-down list 


Role: Specify the role you want to validate for the selected Origin identity trusted providers and 
allowed SP. Click the Validate Rule. 


A list is displayed according to the rule validation for the selected trusted providers, role, and 


permission. 
Configuration 
Trusted Providers | Rules | Construct URL | : 
7) Permit 
Name Identity Providers Service Providers Priority Action Role Conditions Evaluate State 
DENY-Manager- 130logincompany1 127partner2b_sp 1 Deny ! MANAGER(1) Ignored 
122company2_idp 
CEO 130logincompany1 127partner2b_sp 1 Deny CEO(1) Disabled 
Local IDP 
122company2_idp 
DENY-EMP 130logincompany1 127partner2b_sp 1 Deny EMP(1) Disabled 
Local IDP 
Not-Allow-Manager-from-IDP2. 122company2_idp 127partner2b_sp 1 Deny MANAGER(1) Disabled 
122company2_idp 
DENY SPBROLE 130logincompany1 127partner2b_sp 1 Deny SPBROLE(1) Disabled 
Local IDP 
HIGH-RULE Any Any 1 Permit No Role Conditions Configured Disabled 
__Cancel__| 


Name: Displays the role name of the selected trusted providers. 
Identity Providers: Displays the identity provider name. 


Service Providers: Displays the service provider name. 
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Priority: In ascending order, displays the priority number of the rule validation of the selected 
trusted providers. 


Action: Displays the permission action for validation of the selected trusted providers rule 
validation. 


Role Conditions: Displays the role conditions for the selected trusted providers rule validation. 
Denial takes precedence over Permit. 


Evaluate State: Displays the role conditions evaluate state for the selected trusted providers 
rule validation. You can see diffferent evaluation states in the role conditions. 


Pass 1: If the rule matches the Origin identity provider, allowed service provider or any roles 
mentioned. 


Pass2: If the rule matches the Origin identity provider, allowed service provider or any specific 
role mentioned. 


Ignored: If the rule does not match either Pass 1 or Pass 2. 
Not Executed: The default state of all the roles. 


NOTE: If the rule has the evaluate State as Pass 1 action as Deny, then the remaining rules are 
in the non-executed state. 


After a rule has the evaluate state as Pass 2, regardless of the action, the remaining rules are in 
the non-executed state. 


The rules before Pass 1, must have the evaluate state of Ignored. All these ignored rules must 
have the role condition as Any, without specifying any role condition. 


Pass 1 evaluation stops, as soon as a match for the Origin identity provider and allowed service 
provider is found with specific to some role condition. 


4 Click Cancel to close the Rule Validation page. 


5.2.2.4 Generating the Brokering URLs by Using an ID and Target in the 
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Intersite Transfer Service 


You can generate the brokering URL’s using the ID of the target. You can use this value to simplify the 
Intersite Transfer Service URL that must be configured at the service provider. For more information, 
see “Configuring an Intersite Transfer Service Target for a Service Provider” on page 199. 


1 Click Devices > Identity Servers > Brokering or click Devices > Identity Servers > Edit > SAML 
2.0 > Trusted Providers > > (Broker Identity under the Service Providers list) >Intersite Transfer 
Service. 


2 ID: Specify the ID value of the target. 


3 Target: Specify the URL of the page that you want to display to users when they authenticate 
with an Intersite Transfer URL.The behavior of this option is influenced by the Allow any target 
option. If you are using the target ID as part of the Intersite Transfer URL and did not specify a 
target in the URL, you need to specify the target in this field. For example, if you enter the target 
URL as it appears below, then it will be displayed when you select Allow Any Target option. 
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5.2.2.5 


https://login.company1.com:8443/nidp/sam12/ 

idpsend?id=2171ID&TARGET=ht tps%3A%2F%2FSPBROKER1.labs.blr.novell.com%3A8443%2Fn 
idp%2Fsam12%2Fidpsend%3FPID%3Dht t ps%3A%2F%2F login. partner2B.com%3A8443%2Fnidp% 
2Fsam12%2Fmetadata%26TARGET%3Dht t ps%3A%2F%2Fpartner2b.com 


4 Allow any Target: Select this option to use the target that was specified in the Intersite Transfer 
URL. If this option is not selected, the target value in the Intersite Transfer URL is ignored and 
you can see the URL specified in the Target option. 


Assigning The Local Roles Based On Remote Roles And Attributes 


You are able to configure the attributes based on the roles you select in the Attribute set field. You are 
able to log in and authenticated based on roles federated in the Origin Identity Provider, Target 
Service Provider and the Brokering Service Provider configuration. 


Origin Identity Provider Role Attribute Configuration 
1 Click Devices > Identity Servers > Shared Settings >Attribute Sets > Mapping >New. The Add 
Attribute Mapping window displays. 
2 Select the local attribute name from the drop-down list 
3 Enter the remote attribute name for the selected local attribute. 


4 Click OK to add the remote attribute name. The newly added attribute displays in the Mapping 
list. 


5 Click Devices > Identity Servers > Edit > SAML 2.0 > Trusted Providers > (Broker Identity under 
the Identity Providers list) > Configuration > Attributes. 


6 Select the role from drop-down list in the Attribute set. 
7 Using the arrows map the attributes in the Send with Authentication and Available List. 
8 Click Apply to map the set role and attribute of the origin Identity Provider. 


Allowed Service Provider Role Attribute Configuration 
1 Click Devices > Identity Servers > Shared Settings >Attribute Sets > Mapping >New. The Add 
Attribute Mapping window displays. 
Select the local attribute name from the drop-down list. 
Specify the remote attribute name for the selected local attribute. 
Click OK. The newly added attribute displays in the Mapping list. 


ao fF WwW N 


Click Devices > Identity Servers > Edit > SAML 2.0 > Service Providers > (Broker Identity under 
the Service Providers list) > Configuration > Attributes. 


6 Select the role from Attribute set. 
7 Using the arrows, map the attributes in the Send with Authentication and Available List. 


8 Click Apply to map and set the attribute changes to the selected role of the target Identity 
Service Provider. 
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Brokering Service Provider Role Attribute Configuration 


The roles set and the attribute configured in origin identity provider and the target service provider is 
added and mapped in the brokering service provider attribute configuration. 


1 Click Devices > Identity Servers > Shared Settings >Attribute Sets > Mapping >New. The Add 
Attribute Mapping window displays. 

2 Select the local attribute name from the drop-down list 

3 Enter the remote attribute name for the selected local attribute. 


4 Click OK to add the remote attribute name. The newly added attribute displays in the Mapping 
list. 


5 Click Devices > Identity Servers > Brokering or click Devices > Identity Servers > Edit > SAML 
2.0 > Service Providers > (Broker Identity under the Service Providers list) > Configuration > 
Attributes. 


6 Select the role from drop-down list in Attribute set. 
7 Using the arrows map the attributes in Send with Authentication and Available List. 
8 Click Apply to set the role and configure the attribute mappings. 


5.2.2.6 SP Brokering Example 


This example explains how SP Brokering works. Let us assume that two companies Digital Airlines 
and ACME are business partners. There are certain applications that users of both Digital Airlines 
and ACME require to access. 


With SP Brokering, users in Digital Airlines are provided with an intersite transfer URL that allows 
users to authenticate at Digital Airlines, set the assertion at ACME, and give access to the target 
application. With this approach, users do not need to choose from different authentication cards. 
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The following diagram depicts the SP Brokering workflow: 


Origin Identity Provider 


dee 


© 


NetIQ Identity Server 
(SP Broker) 


Allowed Service Provider 


Application / WebServer 
( TARGET ) 


Workflow: 


1. A user is authenticated at Digital Airlines identity provider. The user clicks Broker URL. Digital 
Airlines checks if this user is authenticated. If not, it asks for user credentials and authenticates 
the user. 


2. Digital Airlines identity provider processes an intersite URL and creates an assertion for SP 
Broker (Access Manager Identity Server). 


3. SP Broker receives the assertion and validates that this assertion is received from a trusted 
identity provider. 
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5.2.3 


5.2.3.1 


4. SP Broker checks if the trusted identity provider and the service provider (available in the target 
URL) belong to the same group. SP Broker denies the request if both do not belong to same 
group. 


5. SP Broker sends a request to Digital Airlines identity provider to resolve the artifact. 


6. SP Broker receives the SAML assertion from Digital Airlines identity provider and caches 
attributes/roles received. SP Broker applies any Role policies that have been enabled. 


7. SP Broker performs intersite transfer. In the processing of intersite transfer, SP Broker checks if 
this user was a result of SP Brokering (step 4 earlier). SP Broker enforces the SP Brokering 
rules check: if any of the rules result in deny, an error page is displayed. 


8. SP Broker creates an assertion for ACME. 
9. ACME sends a request to SP Broker to resolve the artifact. 
10. ACME receives the SAML assertion from the SP Broker along with roles/attributes. 


11. ACME sends a redirect to the final target URL. (Note: Redirect happens from ACME’s ESP to 
ACME’s identity provider where the user is already authenticated.) 


12. The user accesses the target application. 


Configuring User Identification Methods for Federation 


Configuring authentication involves determining how the service provider interacts with the identity 
provider during user authentication and federation. Three methods exist for you to identify users from 
a trusted identity provider: 

¢ You can identify users by matching their authentication credentials 


+ You can match selected attributes and then prompt for a password to verify the match, or you 
can use just the attributes for the match. 


+ You can assume that the user does not have an account and create new accounts with user 
provisioning. You can also allow for provisioning when the matching methods fail. If there are 
problems during provisioning, you see error messages with more information. 


The following sections describe how to configure these methods: 


¢ Section 5.2.3.1, “Defining User Identification for Liberty and SAML 2.0,” on page 464 
¢ Section 5.2.3.2, “Defining User Identification for SAML 1.1,” on page 467 
¢ Section 5.2.3.3, “Defining the User Provisioning Method,” on page 468 


¢ Section 5.2.3.4, “User Provisioning Error Messages,” on page 470 


Defining User Identification for Liberty and SAML 2.0 


¢ “Selecting a User Identification Method for Liberty or SAML 2.0” on page 465 
¢ “Configuring the Attribute Matching Method for Liberty or SAML 2.0” on page 466 
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Selecting a User Identification Method for Liberty or SAML 2.0 


User identification determines how an account at the identity provider is matched with an account at 
the service provider. If federation is enabled between the two, the user can set up a permanent 
relationship between the two accounts. If federation is not enabled (see “Configuring a SAML 2.0 
Authentication Request” on page 483 and “Configuring a Liberty Authentication Request” on 

page 513), you cannot set up a user identification method. 


1 Click Devices > Identity Servers > Edit > Liberty [or SAML 2.0] > [Identity Provider] > User 
Identification. 


2 Specify how users are identified on the SAML 2.0 or Liberty provider. Select one of the following 
methods: 


+ Authenticate: Select this option when you want to use login credentials. This option 
prompts the user to log in at both the identity provider and the service provider on first 
access. If the user selects to federate, the user is prompted, on subsequent logins, to 
authenticate only to the identity provider. 


¢ Allow ‘Provisioning’: Select this option to allow users to create an account when they 
have no account on the service provider. 


This option requires that you specify a user provisioning method. 


+ Provision account: Select this option when the users on the identity provider do not have 
accounts on the service provider. This option allows the service provider to trust any user 
that has authenticated to the trusted identity provider 


This option requires that you specify a user provisioning method. 


¢ Attribute matching: Select this option when you want to use attributes to match an identity 
server account with a service provider account. This option requires that you specify a user 
matching method. 


¢ Prompt for password on successful match: Select this option to prompt the user for 
a password when the user’s name is matched to an account, to ensure that the 
account matches. 


NOTE: If you have selected Transient user mapping while configuring the name identifier format, 
the Authenticate and Provision account options are not displayed for SAML 2.0. 


3 Select one of the following: 


+ If you selected the Attribute matching option, select a method, then click OK. If you have 
not created a matching method, continue with “Configuring the Attribute Matching Method 
for Liberty or SAML 2.0” on page 466. 


+ If you selected the Provision account option, select a method, then click OK. If you have 
not created a provisioning method, continue with “Defining the User Provisioning Method” 
on page 468. 


+ Ifyou selected the Authenticate option with the Allow Provisioning option, select a method, 
then click OK. If you have not created a provisioning method, continue with “Defining the 
User Provisioning Method” on page 468. 


+ If you selected the Authenticate option without the Allow Provisioning option, click OK. 
4 Configure the post authentication method. 


Selected Methods: Using the arrow keys to move methods from the Available Methods list to 
the Selected Methods list. The selected method is executed when post remote authentication 
completes. 


For example if you select the passwordfetch method, this method is executed at the service 
provider after the identity provider authentication and federation completes. 
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Logout on method execution failure: If you select this check box, then whenever there is a 
session failure, the user is logged out automatically. 


Configure the session options. 


Allow IDP to set session timeout: Select Allow Identity Provider to set session timeout 
between the principal identified by the subject and the SAML authority based on 
SessionNotOnOrAfter attribute in SAML assertion of authnStatement. 


Overwrite Temporary User: If you select this check box, then the temporary user credentials 
profile got form previous authentication method in the same session will be overwritten with real 
user credentials profile got from this authentication method. 


Overwrite Real User: If you select this check box, then the real user credentials profile got form 
previous authentication method in the same session will be overwritten with real user credentials 
profile got from this authentication method 


Assertion Validity Window: You can manually set the assertion validity time for SAML Service 
Provider (SP) to accommodate clock skew between Service Provider and SAML Identity (IDP) 
Server. 


Click OK twice, then update Identity Server. 


Configuring the Attribute Matching Method for Liberty or SAML 2.0 


If you enabled the Attribute matching option when selecting a user identification method, you must 
configure a matching method. 


The Liberty Personal Profile is enabled by default. If you have disabled it, you need to enable it. See 
“Managing Web Services and Profiles” on page 517. 


1 


Click Devices > Identity Servers > Servers > Edit > Liberty [or SAML 2.0] > [Identity Provider] > 
User Identification. 


2 Click Attribute Matching settings. 


3 Select and arrange the user stores you want to use. 


Order is important. The user store at the top of the list is searched first. If a match is found, the 
other user stores are not searched. 


Select a matching expression, or click New to create a look-up expression. For information about 
creating a look-up expression, see Section 3.5.3, “Configuring User Matching Expressions,” on 
page 83. 


Specify what action to take if no match is found. 


¢ Do nothing: Specifies that an identity provider account is not matched with a service 
provider account. This option allows the user to authenticate the session without identifying 
a user account on the service provider. 


IMPORTANT: Do not select this option if the expected name format identifier is persistent. 
A persistent name format identifier requires that the user be identified so that information 
can be stored with that user. To support the Do nothing option and allow anonymous 
access, the authentication response must be configured for a transient identifier format. To 
view the service provider configuration, see Section 3.9.8, “Configuring an Authentication 
Response for a Service Provider,” on page 193. 


+ Prompt user for authentication: Allows the user to specify the credentials for a user that 
exists on the service provider. Sometimes users have accounts at both the identity provider 
and the service provider, but the accounts were created independently, use different names 
(for example, joe.smith and jsmith) and different passwords, and share no common 
attributes except for the credentials known by the user. 
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+ Provision account: Assumes that the user does not have an account at the service 
provider and creates one for the user. You must create a provisioning method. 


6 Click OK. 


7 (Conditional) If you selected Provision account when no match is found, select the Provision 
settings icon. For information about this process, see “Defining the User Provisioning Method” 
on page 468. 


8 Click OK twice, then update Identity Server. 


5.2.3.2 Defining User Identification for SAML 1.1 


¢ “Selecting a User Identification Method for SAML 1.1” on page 467 
+ “Configuring the Attribute Matching Method for SAML 1.1” on page 468 


Selecting a User Identification Method for SAML 1.1 


Two methods exist for identifying users from an identity provider when using the SAML 1.1 protocol. 
You can specify that no account matching needs to occur, or you can configure a match method. You 
configure a match method when you want to use attributes from the identity provider to uniquely 
identify a user on the service provider. 


1 Click Devices > Identity Servers > Edit > SAML 1.1 > [Identity Provider] > User Identification. 


2 In the Satisfies contract option, specify the contract that can be used to satisfy the assertion 
received from the identity provider. Because SAML 1.1 does not use contracts and because 
Identity Server is contract-based, this setting permits an association to be made between a 
contract and a SAML 1.1 assertion. 

Use caution when assigning the contract to associate with the assertion, because it is possible to 
imply that authentication has occurred, when it has not. For example, if a contract is assigned to 
the assertion, and the contract has two authentication methods (such as one for name/password 
and another for X.509), the server sending the assertion might use only name/password, but the 
service provider might assume that X.509 took place and then incorrectly assert it to another 
server. 


3 Select one of the following options for user identification: 


¢ Do nothing: Specifies that an identity provider account is not matched with a service 
provider account. This option allows the user to authenticate the session without identifying 
a user account on the service provider. 


¢ Attribute matching: Authenticates a user by matching a user account on the identity 
provider with an account on the service provider. This option requires that you set up the 
match method. 


+ Prompt for password on successful match: Specifies whether to prompt the user 
for a password when the user is matched to an account, to ensure that the account 
matches. 


4 Select one of the following: 
+ If you selected Do nothing, continue with Step 6. 


+ If you selected Attribute matching, continue with “Configuring the Attribute Matching 
Method for SAML 1.1” on page 468. 


5 You can also configure the assertion time manually. 


+ Assertion Validity Window: You can manually set the assertion validity time for SAML 
Service Provider (SP) to accommodate clock skew between Service Provider and SAML 
Identity (IDP) Server. 
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5.2.3.3 


6 Click OK twice. 
7 Click Apply to make the user identification configuration changes. 
8 Update Identity Server. 


Configuring the Attribute Matching Method for SAML 1.1 


A user matching expression is a set of logic groups with attributes that uniquely identify a user. User 
matching expressions enable you to map the Liberty attributes to the correct LDAP attributes during 
searches. You must know the LDAP attributes that can be used to identify unique users in the user 
store. 


To use user matching, the Personal Profile must be enabled. It is enabled by default. If you have 
disabled it, you need to enable it. See “Managing Web Services and Profiles” on page 517. 


1 Click Devices > Identity Servers > Servers > Edit > SAML 1.1 > [Identity Provider] > User 
Identification. 

2 To configure the match method, click Attribute Matching settings. 

3 Select and arrange the user stores you want to use. 


Order is important. The user store at the top of the list is searched first. If a match is found, the 
other user stores are not searched. 


4 Select a matching expression, or click New to create a look-up expression. For information about 
creating a look-up expression, see Section 3.5.3, “Configuring User Matching Expressions,” on 
page 83. 


5 Click OK. 
6 Update Identity Server. 


Defining the User Provisioning Method 


If you have selected Provision account as the user identification method or have created an attribute 
matching setting that allows for provisioning when no match is found, you need to create a provision 
method. This procedure involves selecting required and optional attributes that the service provider 
requests from the identity provider during provisioning. 


IMPORTANT: When a user object is created in the directory, some attributes are initially created with 
the value of NAM Generated. Afterwards, an attempt is made to write the required and optional 
attributes to the new user object. Because required and optional attributes are profile attributes, the 
system checks the write policy for the profile’s Data Location Settings (specified in Liberty > Web 
Service Provider) and writes the attribute in either LDAP or the configuration store. For the LDAP 
write to succeed, each attribute must be properly mapped as an LDAP Attribute. Additionally, you 
must enable the read/write permissions for each attribute in the Liberty/LDAP attribute maps. See 
“Mapping LDAP and Liberty Attributes” on page 526. 


To configure user provisioning: 
1 Click Devices > Identity Servers > Servers > Edit > Liberty [or SAML 2.0] > [Identity Provider] > 
User Identification. 
2 Click the Provisioning settings icon. 


3 Select the required attributes from the Available Attributes list and move them to the Attributes 
list. 


Required attributes are those used in the creation of a user name, or that are required when 
creating the account. 
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4 Click Next. 
5 Select optional attributes from the Available Attributes list and move them to the Attributes list. 


This step is similar to selecting required attributes. However, the user provisioning request 
creates the user account whether the optional attributes exist on the service provider. 


6 Click Next. 
7 Define how to create the username. 


You can specify whether users are prompted to create their own usernames or whether the 
system automatically creates usernames. Selecting an attribute for the username segments from 
the required attributes list improves the chances that a new username is successfully created. 


Maximum length: The maximum length of the user name. This value must be between 1 and 
50. 


Prompt for user name: Enables users to create their own usernames. 


Automatically create user name: Specifies that the system creates usernames. You can 
configure the segments for the system to use when creating usernames and configure how the 
names are displayed. 


For example, if you are using the required attributes of Common First Name and Common Last 
Name, a username for Adam Smith might be generated as A.Smith_02, as shown in the 
following illustration: 


Segment 2 


Segment 1 —— A.Smith_02 — Suffix Length 


Junction Junction 


Use the following settings to specify how this is accomplished: 


+ Segment 1: The required attribute to use as the first segment for the user name. The 
values displayed in this drop-down menu correspond to the required attributes you selected. 
For example, you might select Common First Name to use for Segment 1. 


¢ Length: The length of the first attribute segment. For example, if you selected Common 
First Name for the Segment 1 value, setting the length to 1 specifies that the system uses 
the first letter of the Common First Name attribute. Therefore, Adam Smith would be 
ASmith. 


+ Junction: The type of junction to use between the attributes of the user name. If a period is 
selected, Adam Smith would display as A.Smith. 


+ Segment 2: The required attribute to use as the second segment for the user name. The 
values displayed in this drop-down menu correspond to the required attributes you selected. 
For example, you might select Common Last Name to use for Segment 2. 


+ Length: The length of the second attribute segment. For example, if you selected Common 
Last Name for the Segment 2 value, you might set the length to All, so that the full last 
name is displayed. However, the system does not allow more than 20 characters for the 
length of segment 2. 


+ Ensure name is unique: Applies a suffix to the colliding name until a unique name is 
found, if using attributes causes a collision with an existing name. If no attributes are 
provided, or the lengths for them are 0, and this option is selected, the system creates a 
unique name. 


8 Click Next. 
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9 Specify password settings. 


Use this page to specify whether to prompt the user for a password or to create a password 


automatically. 


Min. password length: The minimum length of the password. 


Max. password length: The maximum length of the password. 


Prompt for password: Prompts the user for a password. 


Automatically create password: Specifies whether to automatically create passwords. 


10 Click Next. 


11 Specify the user store and context in which to create the account. 


User Store: The user store in which to create the new user account. 


Context: The context in the user store you want accounts created. 


The system creates the user within a specific context; however, uniqueness is not guaranteed 


across the directory. 


Delete user provisioning accounts if federation is terminated: Specifies whether to 
automatically delete the provisioned user account at the service provider if the user terminates 
his or her federation between the identity provider and service provider. 


12 Click Finish. 
13 Click OK twice, then update Identity Server. 


User Provisioning Error Messages 


The following error messages are displayed for the end user if there are problems during 


provisioning: 
Table 5-1 Provisioning Error Messages 


Error Message 


Username length cannot exceed (?) characters. 
Username is not available. 

Passwords don't match. 

Passwords must be between (x) and (y) 


characters in length. 


Username unavailable. 
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Cause 


The user entered more characters for a user name 
than is allowed, as specified by the administrator. 


The user entered a name that already exists in the 
directory. 


The user provided two password values that do not 
match. 


The user provided password values that are either too 
short or too long. 


The provisioned user account was deleted without first 
defederating the user. Remove orphaned identity 
objects from the configuration datastore. 


IMPORTANT: Only experienced LDAP users must 
remove orphaned identity objects from the 
configuration datastore. You must ensure that the 
objects you are removing are orphaned. Otherwise, 
you create orphaned objects by mistake. 


5.2.4 


5.2.4.1 


Error Message Cause 


Unable to complete authentication request. The password provided does not conform to the 
Windows password complexity policy in Active 
Directory. Ensure that Active Directory is configured to 
use a secure port, such as 636, and that the user's 
password conforms to the complexity policy. If you 
encounter this error, you must reset the password on 
the Windows machine. 


Can occur when users are allowed to create accounts 
from a service provider's login page, when the service 
provider uses Active Directory for the user store. 


Configuring SAML 2.0 


Access Manager has two different ways of configuring a SAML 2.0 federated connection for single 
sign-on to external web services and applications. The heritage way still works and that is what is 
covered in the following sections. The new way of creating a federated SAML 2.0 connection is to use 
the predefined SAML 2.0 connector templates that simplify the configuration process. For more 
information, see “Understanding Federated Single Sign-On with SAML 2.0” in the Access Manager 
Applications Configuration Guide. 


This section explains how to use the SAML 2.0 protocol to set up the trust with internal and external 
identity providers, service providers, and Embedded Service Providers (ESPs). Topics include: 

¢ Section 5.2.4.1, “Understanding How Access Manager Uses SAML,” on page 471 

¢ Section 5.2.4.2, “Configuring a SAML 2.0 Profile,” on page 475 

¢ Section 5.2.4.3, “Managing a SAML 2.0 Service Provider,” on page 476 

¢ Section 5.2.4.4, “Managing a SAML 2.0 Identity Provider,” on page 483 

¢ Section 5.2.4.5, “Defining Options for SAML 2.0,” on page 487 

¢ Section 5.2.4.6, “Configuring the Liberty or SAML 2.0 Session Timeout,” on page 492 

¢ Section 5.2.4.7, “Modifying the Authentication Card for Liberty or SAML 2.0,” on page 492 


¢ Section 5.2.4.8, “Configuring Multiple SAML 2.0 Service Providers on the Same Host for a 
Single SAML Identity Provider,” on page 493 


¢ Section 5.2.4.9, “Configuring Active Directory Federation Services with SAML 2.0 for Single 
Sign-On,” on page 494 


Understanding How Access Manager Uses SAML 


Security Assertions Markup Language (SAML) is an XML-based framework for communicating 
security assertions (user authentication, entitlement, and attribute information) between trusted 
identity providers and trusted service providers. For example, an airline company can make 
assertions to authenticate a user to a partner company or another enterprise application, such as a 
car rental company or hotel. 


Identity Server allows SAML assertions to be exchanged with trusted service providers that use 
SAML servers. Using SAML assertions in each Access Manager component protects confidential 
information by removing the need to pass user credentials between the components to handle 
session management. 
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An identity provider using the SAML protocol generates and receives assertions for authentication, 
according to the SAML 1.0, 1.1, and 2.0 specifications described on the Oasis Standards Web site 
(http://www.oasis-open.org/specs/index.php). 


This section describes how Access Manager uses SAML. It includes the following topics: 


+ “Attribute Mapping with Liberty” on page 472 

+ “Trusted Provider Reference Metadata” on page 472 
+ “Authorization Services” on page 472 

¢ “Identity Provider Process Flow” on page 473 

e “SAML Service Provider Process Flow” on page 474 


Attribute Mapping with Liberty 


Attribute-based mapping involves one website communicating identity information about a subject to 
another website to support transactions. However, the identity information might be some 
characteristic of the subject, such as a role. The attribute-based mapping is important when the 
subject's identity is either not important, must not be shared, or is insufficient on its own. 


To interoperate with trusted service providers through the SAML protocol, Identity Server 
distinguishes between different attributes from different SAML implementations. Access Manager 
uses Liberty attributes in the SAML administration. When you specify which attributes to include in an 
assertion, or which attributes to use when locating the user from an assertion, these attributes must 
always be specified in the Liberty format. 


In an attribute map, SAML attributes from each vendor’s implementation is converted to Liberty 
attributes. (See Section 3.5.1, “Configuring Attribute Sets,” on page 80.) 


You can find detailed information about SAML 2.0 on the OASIS Standards Web site (http:// 
www.oasis-open.org/specs/). 


Trusted Provider Reference Metadata 


Identity Server generates metadata for server communication and identification. You can obtain 
metadata through URL or XML document and then enter it in the system while creating the reference. 
Metadata is traded with federation partners and supplies various information regarding contact and 
organization information located at Identity Server. Metadata is generated automatically for SAML 
2.0. You enter it manually for SAML 1.1. 


IMPORTANT: The SAML 2.0 and Liberty 1.2 protocols define a logout mechanism whereby the 
service provider sends a logout command to the trusted identity provider when a user logs out at a 
service provider. SAML 1.1 does not provide such a mechanism. For this reason, when a logout 
occurs at the SAML 1.1 service provider, no logout occurs at the trusted identity provider. A valid 
session is still running at the identity provider, and no credentials need to be entered. To log out at 
both providers, users must navigate to the identity provider that authenticated them to the SAML 1.1 
service provider and log out manually. 


Authorization Services 


When a user has authenticated to a site or application, the user has access to a resource controlled 
by a Policy Enforcement Point (PEP). The PEP checks for user access to the desired resource. The 
user is either granted or denied access to the resource. SAML is used as the communication 
mechanism between the PEP and a Policy Decision Point (PDP). In NetIQ product terminology, a 
PEP could be thought of as the NetIQ Access Gateway, and the PDP as the NetIQ Identity Server. 
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Identity Provider Process Flow 


The following illustration provides an example of an Identity Server automatically creating an 
authenticated session for the user at a trusted SAML service provider. PP indicates a Personal Profile 
Service as defined by the Liberty specification. 


Figure 5-10 SAML Service Provider Process Flow 
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1. Auser is logged in to Identity Server at abc.com (the user’s identity provider) and clicks a link to 
xyz.com, a trusted SAML service provider. 


Identity Server at abc.com generates the artifact. This starts the process of generating and 
sending the SAML assertion. The HREF would look similar to the following: 


http://nidp.com/saml/genafct?TARGET=http://xyz.com/index.html&AID=XYZ 


2. Identity Server processes attributes as follows: 


a. The server looks up for LDAP or Liberty-LDAP mapped attributes. (See “Mapping LDAP 
and Liberty Attributes” on page 526.) In this example, you use Liberty attributes such as PP: 
sn instead of surname. PP: sn and PP: ph# are attributes that you are sending to xyz.com. 


b. Identity Server processes these attributes with a SAML implementation-specific attribute. 


Because the identity provider must interoperate with other SAML service providers that 
probably do not use consistent attribute names, you can map the service provider attributes 
to your Liberty and LDAP attributes on Identity Server. In this example, the service provider 
names for the Liberty PP: sn and PP: ph# attributes are lastname and phonenumber, 
respectively. (See “Configuring the Attributes Obtained at Authentication” on page 187.) 


c. Identity Server uses the PP service to look up the values for the user's PP: sn and PP: ph# 
attributes. 


Identity Server recognizes that the values for the user's PP: sn and PP: ph# attributes are 
Jones and 555-1212, respectively. 


3. Identity Server sends an HTTP redirect with an artifact. 


Identity Server now has the information to generate a SAML assertion. Identity Server sends an 
HTTP redirect containing the artifact to the browser. The redirect looks similar to the following: 


http://xyz.com/auth/afct?TARGET=http://xyz.com/index.html&SAMLArtifact 
=<<artifact>> 


4. The remote SAML server requests the assertion. 
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The HTTP redirect results in the browser sending the artifact to the SAML server at xyz.com. 
The SAML server at xyz.com requests the SAML assertion from Identity Server. 


5. Identity Server sends the assertion to the remote SAML server. 


The remote SAML server receives the artifact and looks up the assertion. The assertion is sent to 
the SAML server at xyz.com in a SOAP envelope. The assertion contains the attributes 
lastname=Jones and phonenumber=555-1212. 


The user now has an authenticated session at xyz.com. The xyz.com SAML server redirects the 
user’s browser to http://xyz.com/index.html, which was referenced in the original HREF in Step 
1. 


SAML Service Provider Process Flow 


The following illustration provides an example of the authentication process on the consumer side, 
when a user clicks a link at the SAML service provider (xyz.com) to begin an authentication session 
with an identity provider (such as abc.com). PP indicates a Personal Profile Service as defined by the 
Liberty specification. 


Figure 5-11 SAML Consumer Process Flow 
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1. The user clicks a link at xyz.com. 


This generates a SAML assertion intended for Identity Server at abc.com, which is the identity 
provider in an Access Manager configuration. After the SAML server generates the artifact, it 
sends the browser a redirect containing the artifact. The browser is redirected to the identity 
provider, which receives the artifact. The URL sent to Identity Server looks similar to the 
following: 


http://nidp.com/auth/afct?TARGET=http://abc.com/index.html&SAMLArtifact 
=<<artifact>> 


2. Identity Server at abc.com receives the assertion. 


The assertion is sent to Identity Server packaged in a SOAP envelope. In this example, the 
assertion contains the attributes /astname=Jones, and phonenumber=555-1212. 


3. Identity Server determines which attributes to use when locating the user. 


Configuring Authentication 


5.2.4.2 


Identity Server must determine how to locate the user in the directory. When you created the 
SAML service provider reference for xyz.com, you specified which Liberty attributes must be 
used for this purpose. In this case, the you specified that PP: sn and PP: ph# must be used. 


a. Identity Server processes the Liberty attribute map (see “Mapping LDAP and Liberty 
Attributes” on page 526) to the SAML implementation-specific attributes (see “Configuring 
the Attributes Obtained at Authentication” on page 187). 


Because this SAML implementation must interoperate with other SAML implementations 
that probably do not use consistent attribute names, you can map the attributes used by 
each third-party SAML implementation to Liberty attributes on Identity Server. 


b. Identity Server receives implementation-specific SAML attribute names. 


The trusted service provider's names for the Liberty PP: sn and PP: ph# attributes are 
returned. Using the attribute map, Identity Server knows that the service provider's names 
for these attributes are lastname and phonenumber, respectively. 


c. Identity Server uses the PP service to lookup the values for the user’s PP: sn and PP: ph# 
attributes. 


Identity Server now recognizes that the values for the user’s PP: sn and PP: ph# attributes 
are Jones and 555-1212, respectively. The user’s DN is returned to Identity Server, and the 
user is authenticated. 


4. The user’s DN is returned to Identity Server, and the user is authenticated. 
5. The user is redirected to the target resource at xyz.com. 


Configuring a SAML 2.0 Profile 


You can configure the methods of communication that are available at the server for requests and 
responses sent between providers. These settings affect the server metadata, so you must determine 
these prior to publishing to other sites. 


Profiles control the methods of communication that are available for SAML 2.0 protocol requests and 
responses sent between trusted providers. An identity provider uses the incoming metadata to 
determine how to respond. 


All available profile bindings are enabled by default. SOAP is used when all profile bindings are 
enabled (or if the service provider has not specified a preference), followed by HTTP Post, then HTTP 
Redirect. 


1 Click Devices > Identity Servers > Edit > SAML 2.0 > Profiles. 
2 Specify the following details for identity providers and identity consumers (service providers): 


Artifact Resolution: Specify whether to enable artifact resolution for the identity provider and 
identity consumer. 


The assertion consumer service at the service provider performs a back-channel exchange with 
the artifact resolution service at the identity provider. Artifacts are small data objects pointing to 
larger SAML protocol messages. They are designed to be embedded in URL and conveyed in 
HTTP messages. 


Login: Specifies the communication channel to use when the user logs in. Select one or more of 
the following: 


+ Post: A browser-based method used when SAML requester and responder communicate 
through an HTTP user agent. This occurs when the communicating parties do not share a 
direct path of communication. You also use this when the responder requires user 
interaction to fulfill the request, such as when the user must authenticate to it. 
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+ Redirect: A browser-based method that uses HTTP 302 redirects or HTTP GET requests to 
communicate requests from this identity site to the service provider. SAML messages are 
transmitted within URL parameters. 


Single Logout: Specifies the communication channel to use when the user logs out. Select one 
or more of the following options: 


+ HTTP Post: A browser-based method used when the SAML requester and responder need 
to communicate by using an HTTP user agent. This occurs, for example, when the 
communicating parties do not share a direct path of communication. You also use this when 
the responder requires user interaction to fulfill the request, such as when the user must 
authenticate to it. 


+ HTTP Redirect: A browser-based method that uses HTTP 302 redirects or HTTP GET 
requests to communicate requests from this identity site to the service provider. SAML 
messages are transmitted within URL parameters. 


+ SOAP: Uses SOAP back-channel over HTTP messaging to communicate requests from 
this identity provider to the service provider. 


NOTE: If you enable the Show logged out providers option (Identity Servers > Edit > 
Identity Providers) with HTTP Post profile, Access Manager does not complete a logout 
request from the service provider. This occurs because of the difference in the HTTP 
method used in the logout request. It is recommended to use HTTP Redirect method when 
Show logged out providers option is enabled. 


Name Management: Specifies the communication channel for sharing the common identifiers 
for a user between identity providers and service providers. When an identity provider has 
exchanged a persistent identifier for the user with a service provider, the providers share the 
common identifier for a length of time. When either the identity provider or service provider 
changes the format or value to identify the user, the system can ensure that the new format or 
value is properly transmitted. Select one or more of the following options: 


+ HTTP Post: A browser-based method used when the SAML requester and responder need 
to communicate by using an HTTP user agent. This occurs, for example, when the 
communicating parties do not share a direct path of communication. You also use this when 
the responder requires user interaction to fulfill the request, such as when the user must 
authenticate to it. 


+ HTTP Redirect: A browser-based method that uses HTTP 302 redirects or HTTP GET 
requests to communicate requests from this identity site to the service provider. SAML 
messages are transmitted within URL parameters. 


+ SOAP: Uses SOAP back-channel over HTTP messaging to communicate requests from 
this identity provider to the service provider. 


3 Click OK, then update Identity Server. 


4 (Conditional) If you have set up trusted providers and have modified these profiles, reimport 
providers’ metadata from this Identity Server. 


5.2.4.3 Managing a SAML 2.0 Service Provider 
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Topics include: 


¢ “Creating a SAML 2.0 Service Provider” on page 477 
¢ “Contracts Assigned to a SAML 2.0 Service Provider” on page 477 
¢ “Configuring A SAML 2.0 Authentication Response” on page 479 
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¢ “Executing Authorization Based Roles Policy During SAML 2.0 Service Provider Initiated 
Request” on page 480 


¢ “Editing a SAML 2.0 Service Provider’s Metadata” on page 481 
¢ “Configuring Communication Security for a SAML 2.0 Service Provider” on page 482 


Creating a SAML 2.0 Service Provider 


See “Creating a Trusted Service Provider” on page 183. 


Contracts Assigned to a SAML 2.0 Service Provider 


During federation, when a service provider initiates an authentication request, contract information 
may not be available. If the contract information is not available, Identity Server executes a default 
contract for validating the user. You can use the step-up authentication to assign a default contract for 
service providers in such scenarios. 


The following scenario helps you understand the execution of contracts that are assigned to a SAML 
2.0 service provider: 


Figure 5-12 Step-up authentication example with two applications 
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Two web applications Payroll Portal and HR Portal that are protected through different service 
providers use Access Manager Identity Server as an identity provider. A user wants to use the name/ 
password form contract whenever the user accesses the HR application and wants to use the higher 
level contract X509 for the Payroll application. Identity Server provides ability to execute the 
appropriate contract that has been assigned to the service provider instead of executing the default 
contract. 
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The following procedure allows you to assign a specific contract to a service provider: 


1 Click Devices > Identity Servers > Edit > SAML2.0. 


2 Click the configured service provider. 


3 Go to Options > Step Up Authentication contracts and select the contracts from the Available 


contracts list. 


The following table lists the behavior of a service provider request: 


Service Provider Request 


Result 


(Identity Server response if the user is not 
authenticated) 


Service provider request has no contract information to be executed at Identity Server 


1. Identity Server has no contracts set for this service 
provider as in Step 3. 


Execute default contract for validating the user and 
default contract name is sent in the response. 


2. Identity Server has contract C1 set for this service 
provider as in Step 3. 


Service provider requests execution of contract C1 


1. Identity Server has no contracts set for this service 
provider as in Step 3. 


2. Identity Server has contract C1 set for this service 
provider as in Step 3. 


3. Identity Server has contract C2 set for this service 
provider. C2 has trust level check disabled. 


4. Identity Server has contract C2 set for this service 
provider. C2 has trust level check enabled. 


C1 is executed for validating the user and C1 is sent 
in the response. 


at Identity Server 


C1 is executed for validating the user and C1 is sent 
in the response. 


C1 is executed for validating the user and C1 is sent 
in the response. 


C2 is executed for validating the user and C2 is sent 
in the response. 


NOTE: C1 is not considered to be executed in this 
case. 


If trust level of C2 >= trust level of C1, then C2 is 
executed and C2 is sent in the response. 


If trust level of C2 < trust level of C1, then C1 is 
executed and C1 is sent in the response. 


If C1 is not available at Identity Server, then C2 is 
executed and C2 is sent in the response. 


NOTE: When using the service provider (SP) initiated login with a SAML 2.0 SP federation, the SP 
configuration can impact the selection of the Access Manager contract for authentication depending 


on the values sent in SAML authentication request. 


To make it work properly, you must define your 


Access Manager contract URI to match with the request sent by the service provider. 


For more information, see “Allowable Class” in Section 5.1.4, “Configuring Authentication Contracts,’ 


on page 379. 
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Configuring A SAML 2.0 Authentication Response 


After you create a trusted service provider, you can configure how Identity Server responds to 
authentication requests from the service provider. 


1 Click Devices > Identity Servers > Edit > SAML 2.0 > [Service Provider] > Authentication 
Response. 


2 Select the binding method. 


If the request from the service provider does not specify a response binding, you need to specify 
a binding method to use in the response. Select Artifact to provide enhanced security by using a 
back-channel communication between two servers. Select Post to use HTTP redirection for the 
communication channel between two servers. If you select Post, you might require the signing of 
the authentication requests. See “Configuring the General Identity Provider Settings” on 

page 177. 


NOTE: The post binding can be configured to be sent as a compressed option. Perform the 
following steps to achieve this: 


1. 


2. 


Click Devices > Identity Servers > Edit > Options > New. 


Select IS SAML2 POST INFLATE in Property Type and true in Property Value. This provider 
will receive deflated SAML2 POST messages from its trusted providers. 


. Click OK. 


4. Click Devices > Identity Servers > Edit > SAML 2.0 > Service Provider or Identity Provider> 


Options > New. 


. Select SAML2 POST DEFLATE TRUSTEDPROVIDERS in Property Type and specify trusted 


provider's name, metadata URI, or provider ID in Property Value. You can specify multiple 
trusted providers in a comma separated format. These are the trusted providers who expect 
SAML2 POST messages in deflated format. 


6. Click OK. 
7. Restart Identity Server by using the /etc/init.d/novell-idp restart command. 


3 Specify the identity formats that Identity Server can send in its response. Select one or more of 
the following options: 


+ 


Persistent: Specifies that a persistent identifier, which is written to the directory and 
remains intact between sessions, can be sent. 


Transient: Specifies that a transient identifier, which expires between sessions, can be 
sent. 


E-mail: Specifies that an e-mail attribute can be used as the identifier. 
Kerberos: Specifies that a Kerberos token can be used as the identifier. 
X509: Specifies that an X.509 certificate can be used as the identifier. 


Unspecified: Specifies that an unspecified format can be used and any value can be used. 
The service provider and the identity provider need to agree on the value that is placed in 
this identifier. 


4 Use the Default button to select the name identifier that Identity Server must send if the service 
provider does not specify a format. 


If you select E-mail, Kerberos, x509, or unspecified as the default format, you must also select a 
value. See Step 5. 
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IMPORTANT: If you have configured the identity provider to allow a user matching expression to 
fail and still allow authentication by selecting the Do nothing option, you need to select Transient 
identifier format as the default value. Otherwise, the users who fail matching expression are 
denied access. To view the identity provider configuration, see “Defining User Identification for 
Liberty and SAML 2.0” on page 464. 


5 Specify the value for the name identifier. 


The persistent and transient formats are generated automatically. For others, you can select an 
attribute. The available attributes depend upon the attributes that you have selected to send with 
authentication (see “Configuring the Attributes Obtained at Authentication” on page 187). If you 
do not select a value for the E-mail, Kerberos, X509, or Unspecified format, a unique value is 
automatically generated. 


6 To specify that this Identity Server must authenticate the user, deselect Use proxied requests. 
When the option is not selected and Identity Server cannot authenticate the user, the user is 
denied access. 


When this option is selected, Identity Server verifies if other identity providers can satisfy the 
request. If yes, the user is allowed to select the identity provider to perform the authentication. If 
a proxied identity provider performs the authentication, it sends the response to Identity Server. 
Identity Server then sends the response to the service provider. 


N 


If you select Include the Session Timeout attribute in the assertion, Identity Server sends 
Identity Server session time out value to the service provider in the assertion. 


8 You can manually set the assertion validity time for the SAML service provider in the Assertion 


Validity field to accommodate clock skew between the service provider and SAML Identity 
Server (IDP). 


9 Click OK > OK, then update Identity Server. 


Executing Authorization Based Roles Policy During SAML 2.0 Service Provider 
Initiated Request 


Access Manager service provider federation profiles do not allow control based authorization policies. 
Usually, the service providers enforce authorization rules. However, every service provider does not 
have this flexibility. It is recommended not to trust the service provider to enforce such rules. You can 
now apply an authorization policy to a configured service provider to either allow or not to allow 

access to the service provider. Identity Server evaluates service providers and generates assertions. 


Scenario: Company xyz.com uses a CRM application that is protected through a SAML 2.0 service 
provider. This application must only be accessible to the sales team. Whenever a user accesses the 
application through the service provider, it redirects to Identity Server for validating the user. 
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Figure 5-13 Executing Authorization Policy Based on Role 
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Identity Server authenticates the user and then verifies whether the user is a member of the sales 
team. If yes, Identity Server sends a successful assertion to the service provider. Else, Identity Server 
sends an error response to the service provider. 


By default, Identity Server executes these authorization policies after a user is authenticated during 
spsend. Set the ALLOW_AUTH_POLICY_EXECUTION option to false to disable Identity Server to execute 
the authorization policies. For information about how to set this option, see “Configuring Identity 
Server Global Options” on page 75. 


If the authorization policy is configured to deny execution, Identity Server sends the following 
message as part of an assertion response. <samlp:Status> <samlp:StatusCode 
Value="urn:oasis:names:tc:SAML:2.0:status:Responder"> 
<samlp:StatusCodeValue="urn:oasis:names:tc:SAML:2.0:status:RequestDenied" /> </ 
samlp:StatusCode> <StatusMessage>Authorization is failed</StatusMessage> </ 
samlp:Status> 


For more information about configuring a brokering for authorization of service providers, see 
“Configuring a Brokering for Authorization of Service Providers” on page 453. 


Editing a SAML 2.0 Service Provider’s Metadata 
See “Editing a SAML 2.0 Service Provider’s Metadata” on page 190. 
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Configuring Communication Security for a SAML 2.0 Service Provider 


The security settings control the direct communication between Identity Server and the service 
provider across the SOAP back-channel. 
1 Click Devices > Identity Servers > Edit > SAML 2.0. 


2 The Security section specifies how to validate messages received from trusted providers over 
the SOAP back-channel. Both the identity provider and the service provider in the trusted 
relationship must be configured to use the same security method. 


Specify the following details: 
Encrypt assertions: Specifies whether you want the assertions encrypted on the wire. 


Encrypt name identifiers: Specifies whether you want the name identifiers encrypted on the 
wire. 


Certificate Settings: All service providers use the default signing and encryption certificates of 
the identity provider. Specify custom certificates for a service provider as follows: 


¢ Identity Provider Signing Certificate: Select a certificate from the keystore and assign it 
to the service provider. 


¢ Identity Provider Encryption Certificate: Select a certificate from the keystore and assign 
it to the service provider. 


NOTE: When you assign custom certificates to each service provider while configuring 
Identity Server, ensure that you export these certificates and custom metadata to the 
service provider. To retrieve the metadata, click on the metadata link. This link is available in 
the note on the Trust page. 


For example, the default certificates have the following default metadata URL: </DP URL>/ 
nidp/saml2/metadata. 


The custom certificates have the following custom metadata URL for a service provider: 
</DP URL>/nidp/saml2/metadata?PID=<SP Entity ID >. 


+ Certificate Revocation Check Periodicity: Specifies if the certificate is valid or not. Select 
periodicity to validate the certificate. 


SOAP Back Channel Security Method: Select one of the following security methods. 
+ Message Signing: Relies upon message signing by using a digital signature. 


+ Mutual SSL: Specifies that this trusted provider provides a digital certificate (mutual SSL) 
when it sends a SOAP message. 


SSL communication requires only the client to trust the server. For mutual SSL, the server 

must also trust the client. For the client to trust the server, the server’s certificate authority 

(CA) certificate must be imported into the client trust store. For the server to trust the client, 
the clients CA certificate must be imported into the server trust store. 


¢ Basic Authentication: Specifies standard header-based authentication. This method 
assumes that a name and password for authentication are sent and received over the 
SOAP back-channel. 


Send: The name and password to be sent for authentication to the trusted partner. The 
partner expects this password for all SOAP back-channel requests, which means that the 
name and password must be agreed upon. 


Verify: The name and password used to verify data that the trusted provider sends. 
3 Click OK twice. 
4 Update Identity Server. 
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Managing a SAML 2.0 Identity Provider 
Topics include: 


¢ “Creating a SAML 2.0 Identity Provider” on page 483 

e “Configuring a SAML 2.0 Authentication Request” on page 483 

¢ “Configuring Communication Security for a SAML 2.0 Identity Provider” on page 486 

¢ “Defining Session Synchronization for the A-Select SAML 2.0 Identity Provider” on page 487 


Creating a SAML 2.0 Identity Provider 


See “Creating a Trusted Identity Provider” on page 181. 


Configuring a SAML 2.0 Authentication Request 


You can configure how an authentication request is federated. When users authenticate to a service 
provider, they can be given the option to federate their account identities with the preferred identity 
provider. This process creates an account association between the identity provider and service 
provider that enables single sign-on and single log-out. 


The authentication request specifies how you want the identity provider to handle the authentication 
process so that it meets the security needs of Identity Server. 


1 Click Devices > Identity Servers > Edit > SAML 2.0 > [Identity Provider] > Authentication Card 
> Authentication Request. 


2 Configure the name identifier format: 


Persistent: A persistent identifier federates the user profile on the identity provider with the user 
profile on the service provider. It remains intact between sessions. 


The persistent identifier is saved to the user data store and hides the user’s identity to prevent 
tracking of user activities across different relying parties. 


+ After authentication: Specifies that the persistent identifier can be sent after the user has 
authenticated (logged in) to the service provider. When you set only this option, users must 
log in locally. Because the user is required to authenticate locally, you do not need to set up 
user identification. 


¢ During authentication: Specifies that the persistent identifier can be sent when the user 
selects the authentication card of the identity provider. Typically, a user is not authenticated 
at the service provider when this selection is made. When the identity provider sends a 
response to the service provider, the user needs to be identified on the service provider. If 
you enable this option, ensure that you configure a user identification method. See 
“Selecting a User Identification Method for Liberty or SAML 2.0” on page 465. 


Transient: Specifies that a transient identifier, which expires between sessions, can be sent. 
Unspecified: Allows either a persistent or a transient identifier to be sent. 
3 Select one of the following options for the Requested By option: 


Do not specify: Specifies that the identity provider can send any type of authentication to satisfy 
a service provider’s request, and instructs a service provider to not send a request for a specific 
authentication type or contract. 


Use Types: Specifies that authentication types must be used. 
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Select the type of comparison (for more information, see “Understanding Comparison Contexts” 
on page 485): 


+ Exact: Indicates that the class or type specified in the authentication statement must be an 
exact match to at least one contract. 


+ Minimum: Indicates that the contract must be as strong as the class or type specified in the 
authentication statement. 


¢ Better: Indicates the contract that must be stronger than the class or type specified in the 
authentication statement. 


+ Maximum: Indicates that contract must as strong as possible without exceeding the 
strength of at least one of the authentication contexts specified. 


Select the types from the Available types field to specify which type to use for authentication 
between trusted service providers and identity providers. Standard types include Name/ 
Password, X.509, Token, and so on. 


Use Contracts: Specifies that authentication contracts must be used. 
Select the type of comparison (for more information, see “Understanding Comparison Contexts” 
on page 485): 
+ Exact: Indicates that the class or type specified in the authentication statement must be an 
exact match to at least one contract. 


+ Minimum: Indicates that the contract must be as strong as the class or type specified in the 
authentication statement. 


+ Better: Indicates the contract that must be stronger than the class or type specified in the 
authentication statement. 


+ Maximum: Indicates that contract must as strong as possible without exceeding the 
strength of at least one of the authentication contexts specified. 


Select the contract from the Available contracts list. For a contract to appear in the Available 
contracts list, the contract must have the Satisfiable by External Provider option enabled. To 
use the contract for federated authentication, the contract’s URI must be the same on the identity 
provider and the service provider. For information about contract options, see Section 5.1.4, 
“Configuring Authentication Contracts,” on page 379. 


Most third-party identity providers do not support contracts. 
Configure the options: 


Response protocol binding: Select Artifact or Post or Let IDP Decide. Artifact and Post are 
the two methods for transmitting assertions between the authenticating system and the target 
system. 


If you select Let IDP Decide, the binding is selected based on the profile that is enabled at 
Identity Provider and the binding selected in the service provider. 


NOTE: The post binding can be configured to be sent as a compressed option. Perform the 
following steps to achieve this: 


1. Click Devices > Identity Servers > Edit > Options > New. 

2. Select IS SAML2 POST INFLATE in Property Type and true in Property Value. 
3. Click OK. 
4 


. Click Devices > Identity Servers > Edit > SAML 2.0 > Service Provider or Identity Provider> 
Options > New. 
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5. Select SAML2 POST DEFLATE TRUSTEDPROVIDERS in Property Type and enter trusted 
provider's name, metadata URI, or provider ID in Property Value. You can specify multiple 
trusted providers in a comma separated format. These are the trusted providers who expect 
SAML2 POST messages in deflated format. In other words, this provider has to send 
deflated SAML2 POST messages to the listed trusted providers. 


6. Click OK. 
7. Restart Identity Server by using this command: /etc/init.d/novell-idp restart. 


Allowable IDP proxy indirections: Specifies whether the trusted identity provider can proxy the 
authentication request to another identity provider. A value of None specifies that the trusted 
identity provider cannot redirect an authentication request. Values 1-5 determine the number of 
times the request can be proxied. Select Let IDP Decide to let the trusted identity provider decide 
how many times the request can be proxied 


Force authentication at Identity Provider: Specifies that the trusted identity provider must 
prompt users for authentication, even if they are already logged in. 


Use automatic introduction: Attempts single sign-on to this trusted identity provider by 
automatically sending a passive authentication request to the identity provider. (A passive 
requests does not prompt for credentials.) The identity provider sends one of the following 
authentication responses: 


+ When the federated user is authenticated at the identity provider: The identity provider 
returns an authentication response indicating that the user is authenticated. The user gains 
access to the service provider without entering credentials (single sign-on). 


+ When the federated user is not authenticated at the identity provider: The identity 
provider returns an authentication response indicating that the user is not logged in. The 
user can then select a card for authentication, including the card for the identity provider. If 
the user selects the identity provider card, an authentication request is sent to the identity 
provider. If the credentials are valid, the user is also authenticated to the service provider. 


IMPORTANT: Enable the Use automatic introduction option only when you are confident the 
identity provider will be up. If the server is down and does not respond to the authentication 
request, the user gets a page-cannot-be-displayed error. Local authentication is disabled 
because the browser is never redirected to the login page. 


This option must be enabled only when you know the identity provider is available 99.999% of 
the time or when the service provider is dependent upon this identity provider for authentication. 


5 Click OK twice, then update Identity Server. 


Understanding Comparison Contexts 


When a service provider makes a request for an identity provider to authenticate a user, the 
authentication request can contain a class or type and a comparison context. The identity provider 
uses these to determine which authentication procedure to execute. There are four comparison 
contexts: 


+ Exact: Indicates that the class or type specified in the authentication statement must be an exact 
match to at least one contract. 


For example, when the comparison context is set to exact, the identity provider uses the URI in 
the request to find an authentication procedure. If an exact URI match is found, the user is 
prompted for the appropriate credentials. If an exact match is not found, the user is denied 
access. 


¢ Better: Indicates the contract that must be stronger than the class or type specified in the 
authentication statement. 
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If the identity provider is a NetIQ Identity Server, Identity Server first finds the specified class or 
type and its assigned authentication level. It then uses this information to find a contract that 
matches the conditions. For example if the authentication level is set to 1 for the class or type, 
the identity provider looks for a contract with an authentication level that is higher than 1. If one is 
found, the user is prompted for the appropriate credentials. If more than one is found, the user is 
presented with the matching cards and is allowed to select the contract. If a match is not found, 
the user is denied access. 


¢ Minimum: Indicates that the contract must be as strong as the class or type specified in the 
authentication statement. 


If the identity provider is a NetIQ Identity Server, Identity Server first finds the specified class or 
type and its assigned authentication level. It then uses this information to find a contract that 
matches the conditions. For example if the authentication level is set to 1 for the class or type, 
the identity provider looks for a contract with an authentication level of 1 or higher. If one is 
found, the user is prompted for the appropriate credentials. If more than one is found, the user is 
presented with the matching cards and is allowed to select the contract. If a match is not found, 
the user is denied access. 


+ Maximum: Indicates that contract must as strong as possible without exceeding the strength of 
at least one of the authentication contexts specified. 


If the identity provider is a NetIQ Identity Server, Identity Server first finds the specified classes 
or types and their assigned authentication levels. It then uses this information to find a contract 
that matches the conditions. For example if the authentication level is set to 1 for some types 
and 3 for other types, the identity provider looks for contracts with an authentication level of 3. If 
a match or matches are found, the user is presented with the appropriate login prompts. If there 
are no contracts defined with a authentication level of 3, the identity provider looks for a match 
with an authentication level of 2, or if necessary, level 1. It cannot search below the lowest level 
of class in the authentication request or higher than the highest level of a class in the 
authentication request. 


When you configure the authentication request, you specify the comparison context for a type or a 
contract. 


Configuring Communication Security for a SAML 2.0 Identity Provider 


The security settings control the direct communication between Identity Server and an identity 
provider across the SOAP back-channel. 

1 Click Devices > Identity Servers > Edit > SAML 2.0. 

2 Click the name of an identity provider. 

3 On the Trust page, specify the following details: 


Name: Name for this trusted provider. The default name is the name you entered when creating 
the trusted provider. 


The Security section specifies how to validate messages received from trusted providers over 
the SOAP back-channel. Both the identity provider and the service provider in the trusted 
relationship must be configured to use the same security method. 


Encrypt name identifiers: Specifies whether you want the name identifiers encrypted on the 
wire. 


Select one of the following security methods: 
+ Message Signing: Relies upon message signing by using a digital signature. 


+ Mutual SSL: Specifies that this trusted provider provides a digital certificate (mutual SSL) 
when it sends a SOAP message. 
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SSL communication requires only the client to trust the server. For mutual SSL, the server 

must also trust the client. For the client to trust the server, the server’s certificate authority 

(CA) certificate must be imported into the client trust store. For the server to trust the client, 
the client’s CA certificate must be imported into the server trust store. 


+ Basic Authentication: Specifies standard header-based authentication. This method 
assumes that a name and password for authentication are sent and received over the 
SOAP back-channel. 


Send: The name and password to be sent for authentication to the trusted partner. The 
partner expects this password for all SOAP back-channel requests, which means that the 
name and password must be agreed upon. 


Verify: The name and password used to verify data that the trusted provider sends. 


Certificate Revocation Check Periodicity: Specifies if the certificate is valid or not. You 
can define periodicity to validate on start up, on assertion level, or set frequency to hourly/ 
daily. 

Click OK > OK. 

Update Identity Server. 


Defining Session Synchronization for the A-Select SAML 2.0 Identity Provider 


If a user session is active on the service provider, the service provider periodically sends session 
synchronization to Identity Server to maintain the session. You must configure the properties for the 
session synchronization between the service provider and the target identity provider. 


1 


Click Devices > Identity Servers > Servers > Edit > Liberty or SAML 2.0 > Identity Provider > 
Options. 


2 Click New. 
3 Select Other in Property Type. 


4 Specify the following values: 


Property Name: config.aselect.sessionsync.enabled 
Property Value: true 


For session synchronization, add two options, one to enable the session synchronization and the 
other to provide the URL to which synchronization message must be sent. 


The session synchronization message is sent from the Access Manager service provider to the 
A-Select identity provider, in tandem with Access Gateway ESP's activity update. The session 
synchronization message is sent only if the user session is active at Access Gateway portal, 
which is the ESP to the Access Manager service provider. If you log in directly to the Access 
Manager service provider, even if the session is active, the session synchronization message is 
not sent to the A-Select identity provider. 


Click OK, then update Identity Server. 


Defining Options for SAML 2.0 


OIOSAML enables service providers to use external authentication services, implements single sign- 
on across disparate systems, and establishes a foundation for federated identity management. 
OIOSAML enables reuse of authentication services and consistent application of security technology. 


You can implement the Single Logout Profile of OIOSAML. This profile enables you to logout from all 
service providers whose session originate from a particular identity provider. To use this profile, you 
must use a front channel binding. 
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This section includes the following topics: 


¢ “Defining Options for a SAML 2.0 Identity Provider” on page 488 
¢ “Defining Options for a SAML 2.0 Service Provider” on page 490 


Defining Options for a SAML 2.0 Identity Provider 


1 Click Devices > Identity Servers > Servers > Edit > SAML 2.0 > Identity Provider > Options. 


2 Select the required options: 


OIOSAML Compliance: Select this option to make the identity provider OIOSAML compliant. 


Enable Front Channel Logout: Select this option to enable a enable a service provider to 
initiates a logout at the identity provider by using the HTTP Redirect method. 


3 Click New to set SAML properties for an identity provider. The following table lists the available 


properties: 


NOTE: Access Manager 4.2 onwards, configuring the following options through files is 
deprecated. You must configure these option by using Administration Console. 


Property Type 


Extensions 


Property Value 


Specify the value in this format: <samlp:Extensions>. This 
value is sent in the authentication request to this identity 
provider. 


SAML ASSERTION INCLUDE 
MILLISECS 


Select true to get SAML requests for this identity provider 
including the timestamp in millisecond in Issuelnstant. 


SAML2 ATTRIBUTE CONSUMING 
INDEX 


SAML2 AVOID CONSENT 


SAML2 AVOID ISPASSIVE 


SAML2 AVOID NAMEIDPOLICY 


Select the value of AttributeConsumingServicelndex in 
SAML requests to this identity provider from the specified 
integer value. 


Select true to not include Consent as part of the SAML 2.0 
request to this identity provider. 


If you select true, IsPassive is not included in SAML 2.0 
request to this identity provider. 


If you select true, NamelDPolicy is not included in a SAML 
2.0 request to this identity provider. 


SAML2 AVOID PROTOCOLBINDING 


If you select true, ProtocolBinding is not included in a SAML 
2.0 request to this identity provider. 


SAML2 AVOID PROXYCOUNT 


If you select true, ProxyCount is not included in a SAML 2.0 
request to this identity provider. 


SAML2 AVOID SIGN AND VALIDATE 
ASSERTION TRUSTED PROVIDER 
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If you select true, the cluster will accept SAML 2.0 POST 
responses from this provider when the response is signed 
and assertion is not. 


For more information, see “Avoiding Assertion Signing 
Validation” on page 910. 


Property Type Property Value 


SAML2 CHANGE ISSUER Specify the provider ID to be sent as issuer in the SAML 
requests to this identity provider. 


The value is in format {SPProviderlD}->{issuer name}. 
{SPProvider|D} will be replaced by the actual provider ID of 
the service provider. This will set the issuer of SAML 2.0 
requests to the issuer name specified here. 


For example, https://nam.rtreyresearch.net:8443/nidp/saml2/ 
metadata->https://saml.mariagerfjord.dk:8443/nidp/saml2/ 


metadata. 

SAML2 POST DEFLATE If you select true, the cluster will send deflated post 

TRUSTEDPROVIDERS messages to this provider. 

SAML2 SEND ACS INDEX Select true to send AssertionConsumerServicelndex with 
AuthnRequest to this identity provider. 

SAML2 SEND ACS URL Select true to send AssertionConsumerServiceURL with 
AuthnRequest to this identity provider. 

SAML2 SIGN METHODDIGEST Set the value to true to use SHA256 algorithm as signing 

SHA256 algorithm for assertions. 

OTHER Specify Property Name and Value if you want to configure 


any other property for this identity provider. 


SAML2 RESPONSE AVOID REMOVE EXTRANEOUS 
NAMESPACES: Select true to have assertion name space in 
a SAML message and assertion. 


4 Click OK > Apply. 
Sample XML File When All SAML Options Are Set to True 


<samlp:AuthnRequest xmins:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
xmins:saml="urn:oasis:names:tc:SAML:2.0:assertion" AssertionConsumerServicelndex="2" 
ForceAuthn="false" ID="id5R6u1JFtay7eK.ilI97Q3eRI34u8" Issuelnstant="2013-01-18T06:11:26Z" 
Version="2.0"> 


<saml:lssuer> https://nam.rtreyresearch.net:8443/nidp/saml2/metadata</saml:lssuer> 


</samlp:AuthnRequest> 


Sample XML File When All SAML Options Are Set to False 


<samlp:AuthnRequest 
xmiIns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"xmins:saml="urn:oasis:names:tc:SAML:2.0:as 
sertion" AssertionConsumerServicelndex="0" 
AttributeConsumingServiceIndex="2"Consent="urn:oasis:names:tc:SAML:2.0:consent:unavailabl 
e" ForceAuthn="false" ID="idoeZTKq7FOsSMsCigBBCwp30!lqDO0" 
IsPassive="false"Issuelnstant="2013-01- 
23T05:25:32Z"ProtocolBindingProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP- 
POST"Version="2.0"> 


<saml:Issuer> https://saml.mariagerfjord.dk:8443/nidp/saml2/metadata</saml:lssuer> 
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<samlp:NamelDPolicyAllowCreate="true"Format="urn:oasis:names:tc:SAML:2.0:nameid- 
format:persistent"SPNameQualifier="https://nam.rtreyresearch.net:8443/nidp/saml2/metadata"/ 
><samlp:Scoping ProxyCount="5"/> 


</samlp:AuthnRequest> 


Defining Options for a SAML 2.0 Service Provider 


You can use Access Manager as an identity provider for several service providers. You can configure 
a specific authentication contract that is required for a service provider. If you have configured more 
than one authentication contract for a service provider, the contract with minimum level is selected. 


When providing authentication to a service provider, Identity Server ensures that the user is 
authenticated by the required contract. When a user is not authenticated or when a user is 
authenticated, but the authenticated contracts do not satisfy the required contracts, user is prompted 
to authenticate with the required contract. This is called step up authentication. 


If no required contract is configured, then the default contract is executed. 


NOTE: For SAML 2.0, this step up authentication is supported for Intersite Transfer Service (for both 
identity provider initiated and service provider initiated requests). For Liberty, it works only for identity 
provider initiated requests. 


Perform the following steps to define options for a SAML 2.0 service provider: 


1 Click Devices > Identity Servers > Servers > Edit > SAML 2.0 > Service Provider > Options. 
2 Select OIOSAML Compliance to make the service provider OIOSAML compliant. 


The OIOSAML attribute set is automatically populated with the required attributes to send with 
authentication after selecting this option. 


3 Select the required step up authentication contracts from the Available contracts list and move 
them to the Selected contracts list. This is to provide the step up authentication for the service 
provider. 


NOTE: Only the contract that is configured first in the Selected contracts list will be executed. 
This is applicable only for SAML 2.0. 


4 Click New. 
The following table lists the available properties: 


NOTE: Access Manager 4.2 onwards, configuring the following options through files is 
deprecated. You must configure these option by using Administration Console. 


Property Type Description 


SAML ASSERTION INCLUDE MILLISECS Select true to get SAML responses for this 
service provider including the timestamp in 
millisecond in Issuelnstant. 


SAML2 AVOID AUDIENCE RESTRICTION Select true to avoid sending the audience 
restriction information with assertion to this 
service provider. 
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Property Type 


SAML2 AVOID AUTHNCONTEXT CLASS 
REFERENCE 


(Access Manager 4.3 Service Pack 1 and later) 


NOTE: In Access Manager 4.3, you can set this 
property by specifying 
SAML2_AVOID_AUTHN_CONTEXT_CLASS_REF in 
OTHER. 


Description 


Set this to true to exclude 
AuthnContextClassRef as part of the SAML 
2.0 assertion response for this service provider. 


SAML2 AVOID AUTHNCONTEXT DECLARATION 
REFERENCE 


(Access Manager 4.3 Service Pack 1 and later) 


NOTE: In Access Manager 4.3, you can set this 
property by specifying 
SAML2_AVOID_AUTHN_CONTEXT_DECL_REF in 
OTHER. 


Set this to true to exclude 
AuthnContextDeclRef as part of the SAML 
2.0 assertion response for this service provider. 


SAML2 AVOID CONSENT 


Select true to not include Consent as part of the 
SAML 2.0 request. 


SAML2 AVOID SIGN AND VALIDATE ASSERTION 
TRUSTED PROVIDER 


If you select true, the cluster will sign SAML 2.0 
POST responses (excluding the assertion) for 
this provider. 


For more information, see “Avoiding Assertion 
Signing Validation” on page 910. 


SAML2 AVOID SPNAMEQUALIFIER 


Select true to not include SPNAMEQUALIFIER in 
NAMEITDENTIFER in the assertion. 


SAML2 AVOID SPNAMEQUALIFIER TO 


Select true to send SPNAMEQUALIFIER in 
NAMEIDENTIFER with the assertion. 


SAML2 NAMEID ATTRIBUTE NAME 


Specify the LDAP attribute name that will be sent 
in the name identifier in a SAML response for 
this service provider. 


SAML2 POST DEFLATE TRUSTEDPROVIDERS 


If you select true, the cluster will send deflated 
post messages to this provider. 


SAML2 POST SIGN RESPONSE 
TRUSTEDPROVIDERS 


If you select true, the identity provider will sign 
the entire SAML 2.0 response for this service 
provider. 


SAML2 REQUEST IGNORE AUTHCONTEXT 


If you select true, the identity provider ignores 
any specific authentication available in a SAML 
request from this service provider. 


SAML2 SIGN METHODDIGEST SHA256 


If you select true, assertion will use the SHA 256 
algorithm as a hashing algorithm for this service 
provider. 


OTHER 


5 Click OK > Apply. 


Specify Property Name and Value if you want to 
configure any other property for this service 
provider. 


Configuring Authentication 491 


5.2.4.6 


5.2.4.7 


Configuring the Liberty or SAML 2.0 Session Timeout 


When you are active on a session on the service provider and a timeout occurs, the service provider 
initiates a logout. You can configure this timeout by using the web.xml parameter in Access Gateway 
ESP, then ESP initiates a logout message to the Access Manager service provider over the SOAP 
back-channel when the timeout is reached. After the service provider receives this message, it 
creates a SAML 2.0 logout request to the remote identity provider over SOAP. 


To send session timeout message: 
1 Click Devices > Access Gateways > Edit > Reverse Proxy /Authentication > ESP Global 
Options. 
2 Remove the pound (#) symbol before notifysessionTimetolDP and set the value as true. 


ESP sends a ESP session timeout message. After timeout, the service provider sends a 
samlp:LogoutRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol request to 
the remote identity provider. 


3 Restart Tomcat on each Identity Server in the cluster by using the following command: 
Linux: Enter the following command: 
/etc/init.d/novell-idp restart 
Windows: Enter the following commands: 
net stop Tomcat7 


net start Tomcat? 


Session Termination 


If you set the session synchronization between the Service Provider and remote Identity Provider, 
then the remote Identity Provider never sends the logout request to the active Service Provider. 


Modifying the Authentication Card for Liberty or SAML 2.0 


When you create an identity provider, you must also configure an authentication card. After it is 
created, you can modify it. 


1 Click Devices > Identity Servers > Edit > [Protocol] > [Identity Provider] > Authentication Card. 
2 Modify the values in one or more of the following fields: 


ID: If you have need to reference this card outside of the user interface, specify an alphanumeric 
value here. If you do not assign a value, Identity Server creates one for its internal use. The 
internal value is not persistent. Whenever Identity Server is rebooted, it can change. A specified 
value is persistent. 


Text: Specify the text that is displayed on the card to the user. This value, in combination with 
the image, must identify to the users, which provider they are logging into. 


Image: Specify the image to be displayed on the card. Select the image from the drop-down list. 
To add an image to the list, click <Select local image>. 


Show Card: Determine whether the card is shown to the user, which allows the user to select 
and use the card for authentication. If this option is not selected, the card is only used when a 
service provider makes a request for the card. 


NOTE: Do not disable the Show Card option for default contracts. 


492 Configuring Authentication 


5.2.4.8 


Passive Authentication Only: Select this option if you do not want Identity Server to prompt the 
user for credentials. If Identity Server can fulfill the authentication request without any user 
interaction, the authentication succeeds. Otherwise, it fails. 


Satisfies Contract: Select the required contracts from the Available contracts list and move 
them to the Satisfies contract list. 


If the Access Manager identity provider is unable to execute the requested authentication 
contract, it looks for the configured external identity provider. This happens when the Satisfiable 
by External Contract option is enabled that satisfies the incoming authentication (contract) 
request. If the match is found, the identity provider lists all the satisfiable contracts to select the 
appropriate contract. If only a single match is found, the identity provider redirects it to an 
external contract. 


If the local identity provider is able to authenticate by using a local contract, which is satisfiable 
by an external provider, then the first preference is given to the local contract along with the other 
authentication cards listed. 


To configure the contract matching criteria, see “Allowable Class” in Section 5.1.4, “Configuring 
Authentication Contracts,” on page 379. 


3 Click OK > OK and update Identity Server. 


Configuring Multiple SAML 2.0 Service Providers on the Same Host 
for a Single SAML Identity Provider 


When the same Access Manager server hosts more than one SAML service provider and federate 
with another Access Manager acting as an identity provider for these service providers, Access 
Manager must send different sets of attributes in SAML 2.0 assertions to these service providers. 


Perform the following steps to create multiple service providers on the same Access Manager host: 


1 To create multiple service providers from the same identity provider metadata, manually modify 
the identity provider's metadata's entityID for each service provider. You can import the metadata 
text that was edited into the Access Manager configuration to create service providers with 
different entity IDs. 


For more information about how to create a SAML 2.0 service provider, see “Creating a Trusted 
Service Provider” on page 183. 


2 In Administration Console Dashboard of the SAML 2.0 identity provider, click Devices > Identity 
Servers > Servers > Edit > SAML 2.0 > Service Provider > Options > New. 


3 Set the SAML2 AVOID AUDIENCE RESTRICTION property to true. Setting this property to true 
avoids audience restriction in the SAML 2.0 assertion. 


4 To avoid the spnamequalifier attribute in nameidentifier of the assertion, do the following: 


4a In Administration Console Dashboard of the SAML 2.0 service provider, click Devices > 
Identity Servers > Servers > Edit > SAML 2.0 > Service Provider > Options > New. 


4b Set the SAML2 AVOID SPNAMEQUALIFIER TO property to true. 
4c Click OK. 
5 Restart Identity Server. 


NOTE: This is possible only when the identity provider and service providers are deployed on Access 
Manager. 
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5.2.4.9 Configuring Active Directory Federation Services with SAML 2.0 for 
Single Sign-On 


This section describes step-by-step instructions for configuring a basic identity federation deployment 
between Microsoft Active Directory Federation Services 2.0 (AD FS 2.0) and Access Manager by 
using SAML 2.0, specifically its Web Browser SSO Profile and HTTP POST binding. 


You can configure AD FS 2.0 as the claims provider and Access Manager as the relying party, or you 
can configure Access Manager as the claims provider and AD FS 2.0 as the relying party or service 
provider. 


+ 


+ 


“Prerequisites and Requirements” on page 494 


“Configuring Access Manager as a Claims or Identity Provider and AD FS 2.0 as a Relying Party 
or Service Provider” on page 495 


“Configuring AD FS 2.0 as the Claims or Identity Provider and Access Manager as the Relying 
Party or Service Provider” on page 502 


“AD FS 2.0 Basics” on page 505 
“Debugging AD FS 2.0” on page 506 


Prerequisites and Requirements 


Two servers, one to host AD FS 2.0 and the other to host Access Manager. 
AD FS 2.0 is deployed. 
ADFS 2.0 with WIF is deployed. 


The test deployment that was created in the AD FS 2.0 Federation with a Windows Identity 
Foundation (WIF) (http://go.microsoft.com/fwlink/?Linkld=193997) application is used as starting 
point for this deployment. A single Windows Server 2012 instance (fsweb.contoso.com) is used 
to host both the AD FS 2.0 federation server and a WIF sample application. It presumes the 
availability of a Contoso.com domain, in which fsweb.contoso.com is a member server. The 
same computer can act as the domain controller and federation server in the test deployments. 


ADFS 2.0 with SharePoint 2010 is deployed. 


The test deployment that was created in Configuring SharePoint 2010 AAM applications with AD 
FS 2.0 (http://technet.microsoft.com/en-us/library/gg295319.aspx) is used as starting point for 
this deployment. A single Windows Server 2012 instance (fsweb.contoso.com) is used to host 
the AD FS 2.0 federation server and a Windows Server 2012 instance (SP2010) is used to host 
the SharePoint 2010 application. It presumes the availability of a Contoso.com domain, in which 
fsweb.contoso.com is a member server. The same computer can act as the domain controller 
and federation server in the test deployments. 


Access Manager is deployed. 


The Access Manager environment in this deployment is hosted by a fictitious company called 
nam.example.com. Only Identity Server component of Access Manager is required for this 
federation. For more information about installation and deployment of Access Manager, see 
NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


NOTE: You can download the evaluation version of Access Manager from NetlQ’s download portal. 


Linux Environment 


+ 


+ 


Access Manager 4.x.x. 
SUSE Linux Enterprise Server (SLES) 11 SP4 64-bit or a higher version. 
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NOTE: Access Manager supports both Windows and Linux. This section discusses only the Linux 
environment. 


IP Connectivity 


Ensure that the Access Manager (nam.example.com) and AD FS 2.0 (fsweb.contoso.com) systems 
have IP connectivity between them. The Contoso.com domain controller, if it is running on a separate 
computer, does not require IP connectivity to the Access Manager system. If the Access Manager 
firewall is set up, open the ports required for Identity Server to communicate with Administration 
Console. 


For more information about these ports, see Setting Up Firewalls in the NetIQ Access Manager 4.3 
Installation and Upgrade Guide. 


For HTTPS communication, Access Manager Identity Server uses TCP 8443 by default. Your 
browsers need to access this port when using the HTTP POST Binding. Or, you can change this port 
to 443 by using iptables. See Translating the Identity Server Configuration Port in the NetlQ Access 
Manager 4.3 Installation and Upgrade Guide. 


For back-channel communication with cluster members, you need to open two consecutive ports for 
the cluster, such as 7801 and 7802. The initial port (7801) is configurable. See “Configuring a Cluster 
with Multiple Identity Servers” on page 71. 


All federation servers (AD FS and Access Manager) need access to a reliable Network Time Protocol 
(NTP) time source. 


Name Resolution 


The hosts file on the AD FS 2.0 computer (fsweb.contoso.com) is used to configure name resolution 
of the partner federation servers and sample applications. 


Clock Synchronization 


Federation events have a short time to live (TTL). To avoid errors based on time-outs, ensure that 
both computers have their clocks synchronized. 


NOTE: For information about how to synchronize a Windows Server 2012 domain controller to an 
Internet time server, see article 816042 (http://go.microsoft.com/fwlink/?LinkID=60402) in the 
Microsoft Knowledge Base. 


On SLES 11 SP1 64-bit or a higher version, use the command sntp -P no -p pool.ntp.org to 
synchronize time with the Internet time server. 


Configuring Access Manager as a Claims or Identity Provider and AD FS 2.0 as 
a Relying Party or Service Provider 


This section explains how to configure a setup in which an Access Manager user gets federated 
access to the WIF sample application or SharePoint 2010 through AD FS 2.0. This setup uses the 
SAML 2.0 POST profile. 

¢ “Configuring Access Manager” on page 496 

¢ “Configuring AD FS 2.0” on page 497 


e “Example Scenario: Access Manager as the Claims Provider and AD FS 2.0 as the Relying 
Party” on page 501 
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Configuring Access Manager 


+ Using ADFS Metadata to Add a New Service Provider for Access Manager 
+ Exporting the Identity Provider Metadata to a File 


NOTE: To deploy this identity federation, create a new contract with the 
“urn:oasis:names:tc:SAML:2.0:ac:classes:Password” URI and with the name password form method. 
Configure this contract as the default contract. 


Using ADFS Metadata to Add a New Service Provider for Access Manager 
¢ Getting the AD FS 2.0 Metadata 


+ Adding a New Service Provider Connection 

+ Adding an AD FS Server Trusted Certificate 

¢ Creating an Attribute Set in Access Manager 

¢ Configuring the Service Provider in Access Manager 


Getting the AD FS 2.0 Metadata 


1 Access the AD FS server metadata URL at https://<<ADFS (hostname or IP)/ 
FederationMetadata/2007-06/F ederationMetadata.xml. 

2 Save the AD FS metadata file. 

3 Open the AD FS metadata file in any XML editor. 


4 Remove the <RoleDescriptor> tags from the metadata. For example, remove the following 


tags: 

<RoleDescriptor xsi: type="fed:ApplicationServiceType" 
protocolSupportEnumeration=http://.... cee ee S aden .</ 
RoleDescriptor> 


<RoleDescriptor xsi:type="fed:SecurityTokenServiceType" 
protocolSupportEnumeration=http://..... ame > </RoleDescriptor> 


5 Save the changes. 
Adding a New Service Provider Connection 
1 In the Access Manager Administration Console, click Devices > Identity Server > Edit > SAML 
2.0. 
Click New > Add Service Provider. 
In Name, specify a name by which you want to refer to the provider. 
Select Metadata Text from the Source list. 
In Text, paste the copied AD FS metadata that you saved in Step 5. 
Click Next > Finish. 
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Update Identity Server. 
Adding an AD FS Server Trusted Certificate 


1 Download the certificate authority (CA) certificate from the AD FS server. 


2 In Access Manager Administration Console, click Security > Certificates > Trusted Roots > 
Import. 


3 Specify a name for the certificate and browse for the ADFS certificate. 
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4 
5 
6 
7 


Click OK. 

Click Uploaded AD FS CA. 

Click Add to Trusted Store and select config store. 
Update Identity Server. 


Creating an Attribute Set in Access Manager 


1 
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In Access Manager Administration Console, click Devices > Identity Servers > Shared Settings 
> Attribute Sets > click New. 


Provide the attribute set name as adfs-attributes. 
Click Next with the default selections. 

In the Create Attribute Set section, click New. 

Select Idapattribute mail from the Local Attribute list. 
Specify emailaddress in Remote attribute. 


Select http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ from the Remote namespace 
list. 


Click OK. 


9 Click New. 


10 


Select All Roles from the Local Attribute list. 
Specify roles in Remote Attribute. 


Select http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ from the Remote namespace 
list. 


Click OK. 
Update Identity Server. 


Configuring the Service Provider in Access Manager 


1 
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In the Access Manager Administration Console, select the ADFS service provider in the SAML 
2.0 tab. 


Click Authentication Response. 

Select Binding to POST. 

Specify the name identifier format default value and select unspecified along with the defaults. 
Click Attributes. 

Select adfs-attributes from the Attribute Set list. 


Select the required attributes to be sent with authentication. For example, the mail and cn 
attributes. 


Click OK. 


9 Update Identity Server. 


Exporting the Identity Provider Metadata to a File 


Access https://<<Identity server IP / dns name>>:8443/nidp/saml2/metadata in a browser and save 
the page as an XML file, such asnam_metadata. xml. AD FS 2.0 uses this file to automate the setup 
of the Access Manager Claims Provider instance. 


Configuring AD FS 2.0 


+ 


Using Metadata to Add Claims Provider 
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¢ Editing Claim Rules for the Claims Provider Trust 

+ Editing Claim Rules for the WIF Sample Application 

¢ Editing Claim Rules for the SharePoint 2010 Application 
¢ Disabling CRL Checking in the Linux Identity Server 


Using Metadata to Add Claims Provider 


Use the metadata import capabilities of AD FS 2.0 to create the Example.com claims provider. The 
metadata includes the public key that is used to validate security tokens signed by Access Manager. 


Using Metadata to Add a Relying Party 
1 In AD FS 2.0, in the console tree, right-click the Claims Provider Trusts folder, then click Add 
Claims Provider Trust to start the Add Claims Provider Trust Wizard. 
Click Start. 
On the Select Data Source page, select Import data about the claims provider from a file. 
In the Federation metadata file location field, click Browse. 
Navigate to the location where you saved nam_metadata. xml, click Open, then click Next. 
On the Specify Display Name page, type NAM Example. 
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Click Next > Next > Close. 
Editing Claim Rules for the Claims Provider Trust 


The following claim rule describes how the data from Access Manager is used in the security token 
that is sent to the WIF sample application or SharePoint 2010. 


1 In AD FS 2.0, click Relying Party Trusts, right click WIF Sample App, and then click Edit Claim 
Rules. 
or 


In the AD FS 2.0 center pane, under Claims Provider Trusts, right-click NAM Example, then click 
Edit Claim Rules. 


2 On the Acceptance Transform Rules tab, click Add Rule. 
3 On the Select Rule Template page, select the Pass Through or Filter an Incoming Claim option. 
4 Click Next. 
5 On the Configure Claim Rule page, use the following values: 
Name Value 
Claim rule name Name ID Rule 
Incoming claim type Name ID 
Incoming name ID format Unspecified 
6 Select the Pass through all claim values option and click Finish. 
7 Click Add Rule. 
8 On the Select Rule Template page, select the Pass Through or Filter an Incoming Claim option. 
9 Click Next. 


10 On the Configure Claim Rule page, under Claim rule name, specify the following values: 
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Name Value 


Claim rule name Name Rule 


Incoming claim type Name 


11 Keep Pass through all claim values selected and click Finish. 

12 To acknowledge the security warning, click Yes. 

13 Click OK. 

14 Click Add Rule. 

15 On the Select Rule Template page, select Pass Through or Filter an Incoming Claim. 
16 Click Next. 

17 On the Configure Claim Rule page, specify the following values under Claim rule name: 


Name Value 
Claim rule name Email Rule 
Incoming claim type E-Mail Address 


18 Keep Pass through all claim values selected and click Finish. 
19 To acknowledge the security warning, click Yes. 
20 Click OK. 


Editing Claim Rules for the WIF Sample Application 


At this point, incoming claims have been received at AD FS 2.0, but rules that describe what to send 
to the WIF sample application have not yet been created. You need to edit the existing claim rules for 
the sample application to take into account the new Access Manager external claims provider. 

In AD FS 2.0, click Relying Party Trusts. 

Right-click WIF Sample App, then click Edit Claim Rules. 

On the Issuance Transform Rules tab, click Add Rule. 

On the Select Rule Template page, click Pass Through or Filter an Incoming Claim > Next. 
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On the Configure Claim Rule page, specify the following values: 


Name Value 


Claim rule name Pass Name Rule 


Incoming claim type Name 


Keep Pass through all claim values selected, then click Finish. 

On the Issuance Transform Rules tab, click Add Rule. 

On the Select Rule Template page, click Pass Through or Filter an Incoming Claim. 
Click Next. 

10 On the Configure Claim Rule page, specify the following values: 


o ON Oo 
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Name Value 


Claim rule name Pass Name ID Rule 
Incoming claim type Name ID 
Incoming Name ID format Unspecified 


11 Keep Pass through all claim values selected, then click Finish. 
12 Click OK. 


NOTE: If you changed the rules while federating AD FS 2.0 with the WIF sample application, ensure 
that you add the Permit All Users issuance rules back to the WIF sample application. See Step 6: — 
Change Rules in the AD FS 2.0 Federation with a WIF Application Step-by-Step Guide (http:// 
technet.microsoft.com/en-us/library/adfs2-federation-wif-application-step-by-step- 
guide%28WS.10%29.aspx). 


Or, as an alternative, add a new Permit or Deny Users Based on an Incoming Claim rule allowing 
incoming Name ID = john@example.com to access the application. 


Editing Claim Rules for the SharePoint 2010 Application 


At this point, incoming claims have been received at AD FS 2.0, but the rules that describe what to be 
sent to the SharePoint 2010 application have not yet been created. You need to edit the existing claim 
rules for the SharePoint 2010 application, which is added as relying party to ADFS 2.0, to configure 
the new Access Manager external claims provider. 


Editing the Claim Rules for the SharePoint 2010 Application 


In AD FS 2.0, click Relying Party Trusts. 

Right-click SP2010, then click Edit Claim Rules. 

On the Issuance Transform Rules tab, click Add Rule. 

On the Select Rule Template page, click Pass Through or Filter an Incoming Claim > Next. 
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On the Configure Claim Rule page, specify the following values: 


Name Value 


Claim rule name Pass eMail Rule 


Incoming claim type Email Address 


6 Leave the Pass through all claim values option selected and click Finish. 
Using Certificates and Certificate Revocation Lists 


For security reasons, production federation deployments require the use of digitally signed security 
tokens, and optionally allows encryption of the security token contents. Self-signed private key 
certificates, which are generated from inside the AD FS 2.0 and Access Manager products, are used 
for signing security tokens.As an alternative, organizations can use a private key certificate that is 
issued by a certificate authority (CA) for signing and encryption. The primary benefit of using CA- 
issued certificates is the ability to check for possible certificate revocation against the certificate 
revocation list (CRL) from the issuing CA. Also, to avoid the untrusted certificate messages in 
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browsers, the trusted root certificate of the CA must also be imported into your browsers. Many well- 
known CA's trusted roots are included with common browsers. Using one of these existing CAs to 
mint your certificates also prevents the untrusted certificate messages. 


In AD FS 2.0 and in Access Manager, CRL checking is enabled by default for all partner connections, 
if the certificate being used by the partner includes a CRL Distribution Point (CDP) extension. This 
has implications in federation deployments between Access Manager and AD FS 2.0: 


¢ If asigning/encryption certificate provided by one side of a federation includes a CDP extension, 
that location must be accessible by the other side's federation server. Otherwise, CRL checking 
fails, resulting in a failed access attempt. The CDP extensions are added by default to 
certificates that are issued by Active Directory Certificate Services (AD CS) in Windows Server 
2012. 


+ If the signing/encryption certificate does not include a CDP extension, no CRL checking is 
performed by AD FS 2.0 or Access Manager. 
Disabling CRL Checking in the Linux Identity Server 
1 Modify /opt/novell/nam/idp/conf/tomcat .conf and add JAVA_OPTS="${JAVA_OPTS} - 
Dcom.novell.nidp.serverOCSPCRL=false" 
2 To apply the changes, restart Identity Server by running the /etc/init.d/novell-idp restart 
command. 


Disabling CRL Checking in AD FS 2.0 


1 Click Start > Administrative Tools > Windows PowerShell Modules. 
2 Enter the following command at the PowerShell command prompt: 
set-ADFSClaimsProviderTrust -TargetName "NAM Example" 


-SigningCertificateRevocationCheck None 


NOTE: You can make many configuration changes to AD FS 2.0 by using the Windows PowerShell 
command line and scripting environment. For more information, see the AD FS 2.0 Windows 
PowerShell Administration (http://go.microsoft.com/fwlink/?Linkld=194005) section of the AD FS 2.0 
Operations Guide and the AD FS 2.0 Cmdlets Reference (http://go.microsoft.com/fwlink/ 
?LinkId=177389). 


Example Scenario: Access Manager as the Claims Provider and AD FS 2.0 as the Relying 
Party 


+ “Accessing the WIF Sample Application” on page 501 
+ “Accessing the SharePoint 2010 Application” on page 502 


Accessing the WIF Sample Application 


In this scenario, John from Example.com accesses the Contoso WIF sample application. 


NOTE: Clear all the cookies in the Internet Explorer on the AD FS 2.0 computer 
(fsweb.contoso.com). To clear cookies, click Tools > Internet Options > Delete under Browsing 
History, and then select cookies for deletion. 


1 On the AD FS 2.0 computer, open a browser window, then navigate to https:// 
fsweb.contoso.com/ClaimsAwareWebAppWithManagedST S/default.aspx. 


The first page prompts you to select your organization from a list. 
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2 Select NAM Example, then click Continue to sign in. 


When only one Identity Provider is available, AD FS 2.0 forwards the request to that Identity 
Provider by default. 


3 The NAM login page appears. Type the user name john, type the password test, then click 
Login. 
Accessing the SharePoint 2010 Application 


The user's email ID is used as the mapped attribute to access the SharePoint 2010 application. 
Assume that a user is created in the NetIQ Identity Server. The email ID configured for this user is 
namuser1@namidp.com. 


NOTE: Clear all the cookies in the Internet Explorer on the AD FS 2.0 computer 
(fsweb.contoso.com). To clear cookies, click Tools > Internet Options > Delete under Browsing 
History, then select cookies for deletion. 


1 Ensure that an email ID has been configured for the user in the Access Manager user store. 
For this example, use namuser1@namidp.com. 
2 Access the SharePoint 2010 application. 
The user is redirected to AD FS 2.0. 
3 Select NetIQ Identity Server. 
The user is redirected to the NAM IDP nidp page for authentication. 
4 Provide namuser1 as the username and password. 
After authentication, the user is redirected to the SharePoint application. 


Configuring AD FS 2.0 as the Claims or Identity Provider and Access Manager 
as the Relying Party or Service Provider 


This section explains how to configure an application through AD FS 2.0 that gets federated access 
to an application by using Access Manager. The setup uses the SAML 2.0 POST profile. 


¢ “Configuring Access Manager” on page 502 
¢ “Configuring AD FS 2.0” on page 503 


Configuring Access Manager 


The AD FS metadata is used to add an Identity Provider to Access Manager. 


+ “Getting the AD FS 2.0 Metadata” on page 502 

+ “Using the Metadata to Add a New Identity Provider Connection” on page 503 
¢ “Adding the AD FS Server Trusted Certificate” on page 503 

¢ “Configuring the Identity Provider in Access Manager” on page 503 


Getting the AD FS 2.0 Metadata 


1 Access the AD FS server metadata by going to https://<<ADFS hostname or IP/ 
FederationMetadata/2007 -06/FederationMetadata. xml 

2 Save the AD FS metadata data. 

3 Open the AD FS metadata file in Notepad, WordPad, or an XML editor). 

4 Remove the <RoleDescriptor> tags from the metadata. 
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For example, remove the following tags: 


"<RoleDescriptor xsi: type="fed:ApplicationServiceType" 


protocolSupportEnumeration=httpi//.. cee ee Pe deceased .</ 
RoleDescriptor> 
"<RoleDescriptor xsi: type="fed:SecurityTokenServiceType" 
protocolSupportEnumeration=http://.. 2... sees > </RoleDescriptor> 
5 Save the changes. 
Using the Metadata to Add a New Identity Provider Connection 
1 In the Access Manager Administration Console, select Devices > Identity Server. 
2 Click Edit. 
3 Select SAML 2.0. 
4 Click New > Identity Provider. 
5 Specify the name as ADFS in the Name field. 
6 Select Metadata Text from the Source list. 
7 Paste the copied ADFS metadata that you saved in Step 5 on page 503 into the Text field. 
8 Click Next. 
9 Specify an alphanumeric value that identifies the card in the ID field. 
10 Specify the image to be displayed on the card in the Image field. 
11 Update Identity Server. 
Adding the AD FS Server Trusted Certificate 
1 Retrieve the AD FS server's CA trusted root certificate. 
2 In the Access Manager Administration Console, select Security > Certificates. 
3 Select Trusted Roots. 
4 Click Import. 
5 Specify the certificate name, and browse for the AD FS certificate authority. 
6 Click OK. 
7 Click uploaded AD FS CA. 
8 Click Add to Trusted Store and select config store. 
9 Update Identity Server. 
Configuring the Identity Provider in Access Manager 
1 Select the AD FS Identity Provider in the SAML 2.0 tab. 
2 Click Authentication Card > Authentication Request. 
3 Select Response Protocol Binding to POST. 
4 Select NAME Identifier Format as Transient. 
5 Click OK. 
6 Update Identity Server. 
Configuring AD FS 2.0 
+ “Using the Metadata to Add a Relying Party” on page 504 
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¢ “Editing Claim Rules for a Relying Party Trust” on page 504 
¢ “Disabling the Certificate Revocation List” on page 505 
+ “AD FS 2.0 Encryption Strength” on page 505 


Using the Metadata to Add a Relying Party 


The metadata import capability of AD FS 2.0 is used to create a relying party. The metadata includes 
the public key that is used to validate security tokens signed by Access Manager. 


1 In AD FS 2.0, right-click the Relying Party Trusts folder, then click Add Relying Party Trust to 
start the Add Relying Party Trust Wizard. 

Click Start. 

On the Select Data Source page, select Import data about the claims provider from a file. 


In the Federation metadata file location section, click Browse. 
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Navigate to the location where you saved nam_metadata.xml earlier, select the file, then click 
Open > Next. 


o 


On the Specify Display Name page, specify NAM Example. 
7 Click Next > Next > Close. 
Editing Claim Rules for a Relying Party Trust 
The data from AD FS is used in the security token that is sent to Access Manager. 
1 The Edit Claim Rules dialog box must already be open. If not, in the AD FS 2.0 center pane, 
under Relying Party Trusts, right-click NAM Example, then clickEdit Claim Rules. 
2 On the Issuance Transform Rules tab, click Add Rule. 


3 On the Select Rule Template page, leave the Send LDAP Attributes as Claims option selected, 
then click Next. 


4 On the Configure Claim Rule page, specify Get attributes in the Claim rule name field. 
5 Select Active Directory from the Attribute Store list. 
6 In the Mapping of LDAP attributes section, create the following mappings: 


LDAP Attribute Outgoing Claim Type 
User-Principal-Name UPN 
E-Mail-Address E-Mail Address 

7 Click OK. 


8 Click Apply > OK. 

9 On the Issurance Transform Rules tab, click Add Rules. 
10 On the Select Rule Template page, select Transform an Incoming Claim, then click Next. 
11 On the Configure Claim Rule page, use the following values: 
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Name Value 


Claim rule name Mapping To Transient Name Identifier 
Incoming Claim Type UPN 

Outgoing Claim Type Name ID 

Outgoing name ID format Transient Identifier 


12 Select Pass Through All Claims, then click OK. 
13 Click Apply > OK. 


Disabling the Certificate Revocation List 


For more information about signing and encryption certificates, see “Using Certificates and Certificate 


Revocation Lists” on page 500. 


Disabling the CRL Checking Option in the Linux Identity Provider 


Modify the /opt/novell/nam/idp/conf/tomcat .conf file and add JAVA_OPTS="${JAVA_OPTS} - 


Dcom.novell.nidp.serverOCSPCRL=false" 
Disabling the CRL Checking Option in AD FS 2.0 


1 Click Start > Administrative Tools > Windows PowerShell Modules. 
2 Enter the following command at the PowerShell command prompt: 
set-ADFSRelyingPartyTrust -TargetName "NAM Example" 


-SigningCertificateRevocationCheck None 
AD FS 2.0 Encryption Strength 


In AD FS 2.0, encryption of the outbound assertions is enabled by default. Assertion encryption 
occurs for any relying party or service provider for which AD FS 2.0 possesses an encryption 
certificate. AD FS 2.0 uses 256-bit Advanced Encryption Standard (AES) keys or AES-256 for 
encryption. In contrast, Failing to reconcile these conflicting defaults can result in the failed SSO 
attempts. To resolve this issue, disable the encryption in AD FS 2.0. 

1 InAD FS 2.0, click Start > Administrative Tools > Windows PowerShell Modules. 

2 Enter the following command in at the PowerShell command prompt: 

set-ADFSRelyingPartyTrust -TargetName "NAM Example" 


-EncryptClaims $False 


AD FS 2.0 Basics 


¢ “Configuring the Token-Decrypting Certificate” on page 505 
+ “Adding CA Certificates to AD FS 2.0” on page 506 


Configuring the Token-Decrypting Certificate 


1 Open the AD FS 2.0 Management tool, then click Start > Administrative Tools > AD FS 2.0 
Management. 


2 In the left pane, expand the Service folder and click Certificates. 
3 In the Certificates section, select Add Token-Decrypting Certificate. 
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4 (Conditional) If you see an error prompting you to run certain commands during the token- 
decrypting process, run the following PowerShell commands: 


Add-PSSnapin Microsoft .Adfs.PowerShell 
Set-ADFSProperties -AutoCertificateRollover $false 


These commands allow you to select other certificates. The certificate must be installed on the 
server. The certificates are configured on the IIS Manager. 


5 Click Start > Administrative Tools > Internet Information Services (IIS) Manager. 
6 Click ServerName. 


7 Click Server Certificates in the IIS section. 
Adding CA Certificates to AD FS 2.0 


1 In Windows, Start > Run > mmc. 

2 Attach snapshot certificates as service. 

3 Select AD FS. 

4 Import the CA certificate to trusted authorities. 


Debugging AD FS 2.0 


1 In the Event Viewer, click Applications > AD FS. You can access the troubleshooting help at 
Troubleshooting certificate problems with AD FS 2.0 (http://technet.microsoft.com/en-us/library/ 
adfs2-troubleshooting-certificate-problems%28WS.10%29.aspx)”’. 


Power Shell Commands Help: 
+ Using Windows PowerShell for AD FS2.0 (http://technet.microsoft.com/en-us/library/adfs2-help- 
using-windows-powershell%28WS.10%29.aspx) 


+ AD FS 2.0 for Windows PowerShell Examples (http://technet.microsoft.com/en-us/library/adfs2- 
powershell-examples%28WS.10%29.aspx) 


Configuring SAML 1.1 


This section explains how to use the SAML 1.1 protocol to set up the trust with internal and external 
identity providers, service providers, and Embedded Service Providers (ESPs). Topics include: 

¢ Section 5.2.5.1, “Configuring a SAML 1.1 Profile,” on page 507 

¢ Section 5.2.5.2, “Creating a SAML 1.1 Service Provider,” on page 507 

¢ Section 5.2.5.3, “Creating a SAML 1.1 Identity Provider,” on page 507 

¢ Section 5.2.5.4, “Configuring Communication Security for SAML 1.1,” on page 507 

¢ Section 5.2.5.5, “Editing a SAML 1.1 Identity Provider’s Metadata,” on page 507 

¢ Section 5.2.5.6, “Editing a SAML 1.1 Service Provider’s Metadata,” on page 507 

¢ Section 5.2.5.7, “Configuring the SAML 1.1 Authentication Response,” on page 508 

¢ Section 5.2.5.8, “Defining Options for SAML 1.1 Service Provider,” on page 508 

¢ Section 5.2.5.9, “Modifying the Authentication Card for SAML 1.1,” on page 508 
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5.2.5.1 


5.2.5.2 


5.2.5.3 


5.2.5.4 


5.2.5.5 


5.2.5.6 


Configuring a SAML 1.1 Profile 


You can configure the methods of communication that are available at the server for requests and 
responses sent between providers. These settings affect the metadata for the server and must be 
determined prior to publishing to other sites. 


Profiles control what methods of communication are available at the server for the SAML 1.1 protocol. 
These settings affect the metadata for the server and must be determined prior to publishing to other 
sites. If you have set up trusted providers, and then modify these profiles, the trusted providers need 
to reimport the metadata from this Identity Server. 

1 Click Devices > Identity Servers > Edit > SAML 1.1 > Profiles. 

2 Configure the following fields: 


Login: Specifies the communication channel when the user logs in. Select one or more of these 
methods for the identity provider and the identity consumer: 


+ The Artifact binding provides an increased level of security by using the back channel for 
communication between the two servers during authentication. 


+ The Post method uses HTTP redirection to accomplish communication between servers. 


The Post method is enabled by default and you are not able to modify the default 
settings.The Post profile creates a metadata that includes only a Post binding on the 
Service Provider. If you have the default setup, then always both Artifact and Post options 
are enabled. If both the options are enabled, then by default Artifact binding is used. If 
Artifcact binding is disabled or removed, only Post method is used. 


Source ID: Displays the hexadecimal ID generated by Identity Server for the SAML 1.1 service 
provider. This is a required value when establishing trust with a service provider. 


3 Click OK, then update Identity Server. 


4 (Conditional) If you have set up trusted providers and have modified the profile, these providers 
need to reimport the metadata from this Identity Server. 


Creating a SAML 1.1 Service Provider 


See “Creating a Trusted Service Provider” on page 183. 


Creating a SAML 1.1 Identity Provider 


See “Creating a Trusted Identity Provider” on page 181. 


Configuring Communication Security for SAML 1.1 


Liberty and SAML 1.1 have the same security options for the SOAP back channel for both identity 
and service providers. See “Configuring Communication Security for Liberty” on page 512 


Editing a SAML 1.1 Identity Provider’s Metadata 


See “Editing a SAML 1.1 Identity Provider's Metadata” on page 191. 


Editing a SAML 1.1 Service Provider’s Metadata 


See “Editing a SAML 1.1 Service Provider’s Metadata” on page 192. 
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5.2.5.7 


5.2.5.8 


5.2.5.9 


Configuring the SAML 1.1 Authentication Response 


You can specify the name identifier and its format when Identity Server sends an authentication 
response. You can also restrict the use of the assertion. 


When an identity provider sends an assertion, the assertion can be restricted to an intended 
audience. The intended audience is defined to be any abstract URI in SAML 1.1. The URL reference 
can also identify a document that describes the terms and conditions of audience membership. 


1 Click Devices > Identity Servers > Edit > SAML 1.1 > [Service Provider] > Authentication 
Response. 
2 To specify a name identifier format, select one of the following: 
+ E-mail: Specifies that an e-mail attribute can be used as the identifier. 
+ X509: Specifies that an X.509 certificate can be used as the identifier. 


+ Unspecified: Specifies that an unspecified format can be used and any value can be used. 
The service provider and the identity provider need to agree on what value is placed in this 
identifier. 


3 To specify the format of the name identifier, select an attribute. 


The available attributes depend upon the attributes that you have selected to send with 
authentication (see the Attributes page for the service provider). 


4 To configure an audience, click New. 
5 Specify the SAML Audience URL value. 


The Provider ID, which can be used for the audience, is displayed on the Edit page for the 
metadata. 


6 You can manually set the assertion validity time for the SAML service provider in the Assertion 
Validity field to accommodate clock skew between the service provider and SAML Identity 
Server (IDP). 


7 Click OK twice, then update Identity Server. 


Defining Options for SAML 1.1 Service Provider 


For more information about Options, see “Defining Options for a SAML 2.0 Service Provider” on 
page 490 
1 Click Devices > Identity Servers > Servers > Edit > SAML 1.1 > Service Provider > Options. 


2 Select the required step up authentication contracts from the Available Contracts list and move 
them to the Selected Contracts list. These selected contracts will be used to provide the step up 
authentication for the service provider. 


3 Click OK. 


Modifying the Authentication Card for SAML 1.1 


When you create an identity provider, you must also configure an authentication card. After it is 
created, you can modify it. 


1 Click Devices > Identity Servers > Edit > SAML 1.1 > [Identity Provider] > Authentication Card. 
2 Modify the values in one or more of the following fields: 


508 Configuring Authentication 


ID: If you have need to reference this card outside of the user interface, specify an alphanumeric 
value here. If you do not assign a value, Identity Server creates one for its internal use. The 
internal value is not persistent. Whenever Identity Server is rebooted, it can change. A specified 
value is persistent. 


Text: Specify the text that is displayed on the card to the user. This value, in combination with 
the image, must identify to the users, which provider they are logging into. 


Login URL: Specify an Intersite Transfer Service URL.The URL has the following format, where 
idp.sitea.novell.com is the DNS name of the identity provider, idp.siteb.novell.com is the name of 
the service provider, and idp.siteb.novell.com:8443/nidp/app specifies the URL that you want to 
users to access after a successful login. 


NOTE: The PID in the login URL must exactly match the entity ID specified in the metadata. 


https://idp.sitea.novell.com:8443/nidp/saml/idpsend?PID=https:// 
idp.siteb.novell.com:8443/nidp/saml/metadata&TARGET=https:// 
idp.siteb.novell.com:8443/nidp/app 


For more information, see “Specifying the Intersite Transfer Service URL for the Login URL 
Option” on page 196. 

If your identity provider is a Access Manager Identity Server and you know the ID specified for 
the target, you can use the following simplified format for the Login URL: 

<URL for site a>?id=<ID of target> 


https://idp.sitea.novell.com:8443/nidp/saml/idpsend?id=206test 


The target and the target ID are specified in the service provider configuration at the identity 
provider. See “Configuring an Intersite Transfer Service Target for a Service Provider” on 
page 199. 


Image: Specify the image to be displayed on the card. Select the image from the drop-down list. 
To add an image to the list, click <Select local image>. 


Show Card: Determine whether the card is shown to the user, which allows the user to select 
and use the card for authentication. If this option is not selected, the card is only used when a 
service provider makes a request for the card. 


3 Click OK twice, then update Identity Server. 


5.2.6 Configuring Liberty 


This section explains how to use the Liberty protocol to set up the trust with internal and external 
identity providers, service providers, and Embedded Service Providers (ESPs). Topics include: 

¢ Section 5.2.6.1, “About Liberty,” on page 510 

¢ Section 5.2.6.2, “Configuring a Liberty Profile,” on page 511 

¢ Section 5.2.6.3, “Creating a Liberty Service Provider,” on page 511 

e Section 5.2.6.4, “Creating a Liberty Identity Provider,” on page 512 

¢ Section 5.2.6.5, “Configuring Communication Security for Liberty,” on page 512 

e Section 5.2.6.6, “Configuring a Liberty Authentication Request,” on page 513 

¢ Section 5.2.6.7, “Configuring the Liberty Authentication Response,” on page 514 

¢ Section 5.2.6.8, “Defining Options for Liberty Service Provider,” on page 515 

¢ Section 5.2.6.9, “Defining Options for Liberty Identity Provider,” on page 515 
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¢ Section 5.2.6.10, “Configuring the Session Timeout,” on page 516 
¢ Section 5.2.6.11, “Modifying the Authentication Card,” on page 516 


About Liberty 


The Liberty Alliance is a consortium of business leaders with a vision to enable a networked world in 
which individuals and businesses can more easily conduct transactions while protecting the privacy 
and security of vital identity information. 


To accomplish its vision, the Liberty Alliance established an open standard for federated network 
identity through open technical specifications. In essence, this open standard is a structured version 
of the Security Assertions Markup Language, commonly referred to as SAML, with the goal of 
accelerating the deployment of standards-based single sign-on technology. 


For general information about the Liberty Alliance, visit the Liberty Alliance Project Web site (http:// 
www.projectliberty.org/). 


Liberty resources, including specifications, white papers, FAQs, and presentations, can be found at 
the Liberty Alliance Resources Web site (http:/Awww.projectliberty.org/liberty/resource_center/). 


The following table provides links to specific Liberty Alliance specifications: 
Table 5-2 Liberty Alliance Links 


Liberty Specification Location 


Liberty Alliance Project Overview Liberty Alliance Project Overview (http:// 
www. projectliberty.org/) 


Liberty White Papers Papers (http:/Awww.projectliberty.org/liberty/ 
resource_center/papers) 


Identity Federation Specifications Liberty ID-FF 1.2 Specification (http:// 
www.projectliberty.org/resources/ 
specifications.php#box1 ) 


Web Service Framework Specifications Liberty ID-WSF 1.1 Specifications (http:// 
www.projectliberty.org/resources/ 
specifications.php#box2a) 


Liberty Profile Service Specifications Liberty Alliance ID-SIS 1.0 Specifications (http:// 
www.projectliberty.org/resources/ 
specifications.php#box3) 


OASIS Standards (SAML) Oasis Standards (http://www.oasis-open.org/specs/ 
index.php#samlv2.0) 
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Configuring a Liberty Profile 


You can configure the methods of communication that are available at the server for requests and 
responses sent between providers. These settings affect the metadata for the server and must be 
determined prior to publishing to other sites. 


The profile specifies what methods of communication are available at the server for the Liberty 
protocol. These settings affect the metadata for the server and must be determined prior to publishing 
to other sites. If you have set up trusted providers, and then modify these profiles, the trusted 
providers need to reimport the metadata from this Identity Server. 


1 Click Devices > Identity Servers > Edit > Liberty > Profiles. 
2 Configure the following fields for identity providers and service providers: 


Login: Specifies whether to support Artifact or Post binding for login. Select one or more of the 
following for the identity provider and the service provider: 


¢ The Artifact binding provides an increased level of security by using a back channel means 
of communication between the two servers during authentication. 


+ The Post method uses HTTP redirection to accomplish communication between the 
servers. 


Single Logout: Specifies the communication method to use when the user logs out. Typically, 
you select both of these options, which enables the identity provider or service provider to accept 
both HTTP and SOAP requests. SOAP is used if both options are selected, or if the service 
provider has not specified a preference. 


+ HTTP: Uses HTTP 302 redirects or HTTP GET requests to communicate logout requests 
from this identity site to the service provider. 


+ SOAP: Uses SOAP over HTTP messaging to communicate logout requests from this 
identity provider to the service provider. 


Federation Termination: Specifies the communication channel to use when the user selects to 
defederate an account. Typically, you select both of these options, which enables the identity 
provider or service provider to accept both HTTP and SOAP requests. SOAP is the default 
setting if the service provider has not specified a preference. 


+ HTTP: Uses HTTP 302 redirects to communicate federation termination requests from this 
server. 


+ SOAP: Uses SOAP back channel over HTTP messaging to communicate logout requests 
from this server 


Register Name: Specifies the communication channel to use when the provider supplies a 
different name to register for the user. Typically, you select both of these options, which enables 
the identity provider or service provider to accept both HTTP and SOAP requests. SOAP is the 
default setting if the service provider has not specified a preference. 


+ HTTP: Uses HTTP 302 redirects to communicate federation termination requests from this 
server. 


+ SOAP: Uses SOAP back channel over HTTP messaging to communicate logout requests 
from this server. 


3 Click OK, then update Identity Server. 


(Conditional) If you have set up trusted providers and have modified the profile, these providers 
need to reimport the metadata from this Identity Server. 


5.2.6.3 Creating a Liberty Service Provider 


See “Creating a Trusted Service Provider” on page 183. 
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5.2.6.4 Creating a Liberty Identity Provider 


See “Creating a Trusted Identity Provider” on page 181. 


5.2.6.5 Configuring Communication Security for Liberty 


Liberty and SAML 1.1 have the same security options for the SOAP back channel for both identity 
and service providers. You cannot configure the trust relationship of the SOAP back channel for 
Identity Server and its Embedded Service Providers. 
1 Click Devices > Identity Servers > Edit > [Protocol]. 
For the protocol, select either Liberty or SAML 1.1. 
2 Click the name of a provider. 
3 On the Trust page, fill in the following field: 


Name: Specify the display name for this trusted provider. The default name is the name you 
entered when creating the trusted provider. 


For an Embedded Service Provider, the Name option is the only available option on the Trust 
page. 


The Security section specifies how to validate messages received from trusted providers over 
the SOAP back channel. Both the identity provider and the service provider in the trusted 
relationship must be configured to use the same security method. 


4 Select one of the following security methods: 
Message Signing: Relies upon message signing using a digital signature. 


Mutual SSL: Specifies that this trusted provider provides a digital certificate (mutual SSL) when 
it sends a SOAP message. 


SSL communication requires only the client to trust the server. For mutual SSL, the server must 
also trust the client. For the client to trust the server, the server’s certificate authority (CA) 
certificate must be imported into the client trust store. For the server to trust the client, the client's 
CA certificate must be imported into the server trust store. 


Basic Authentication: Specifies standard header-based authentication. This method assumes 
that a name and password for authentication are sent and received over the SOAP back 
channel. 


+*+ Send: The name and password to be sent for authentication to the trusted partner. The 
partner expects this password for all SOAP back-channel requests, which means that the 
name and password must be agreed upon. 


+ Verify: The name and password used to verify data that the trusted provider sends. 
5 Click OK twice. 
6 Update Identity Server. 
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Configuring a Liberty Authentication Request 


You can configure how Identity Server creates an authentication request for a trusted identity 
provider. When users authenticate, they can be given the option to federate their account identities 
with the preferred identity provider. This process creates an account association between the identity 
provider and service provider that enables single sign-on and single log-out. 


The authentication request specifies how you want the identity provider to handle the authentication 
process so that it meets the security needs of Identity Server. 


1 Click Devices > Identity Servers > Edit > Liberty > [Identity Provider] > Authentication Card > 
Authentication Request. 


2 Configure the federation options: 


Allow Federation: Determines whether federation is allowed. The federation options that 
control when and how federation occurs can only be configured if the identity provider has been 
configured to allow federation. 


+ After authentication: Specifies that the federation request can be sent after the user has 
authenticated (logged in) to the service provider. When you set only this option, users must 
log in locally, then they can federate by using the Federate option on the card in the Login 
page of the Access Manager User Portal. Because the user is required to authenticate 
locally, you do not need to set up user identification. 


¢ During authentication: Specifies whether federation can occur when the user selects the 
authentication card of the identity provider. Typically, a user is not authenticated at the 
service provider when this selection is made. When the identity provider sends a response 
to the service provider, the user needs to be identified on the service provider to complete 
the federation. If you enable this option, ensure that you configure a user identification 
method. See “Selecting a User Identification Method for Liberty or SAML 2.0” on page 465. 


3 Select one of the following options for the Requested By option: 


Do not specify: Specifies that the identity provider can send any type of authentication to satisfy 
a service provider's request, and instructs a service provider to not send a request for a specific 
authentication type or contract. 


Use Types: Specifies that authentication types must be used. 


Select the types from the Available types field to specify which type to use for authentication 
between trusted service providers and identity providers. Standard types include Name/ 
Password, Secure Name/Password, X509, Token, and so on. 


Use Contracts: Specifies that authentication contracts must be used. 


Select the contract from the Available contracts list. For a contract to appear in the Available 
contracts list, the contract must have the Satisfiable by External Provider option enabled. To 
use the contract for federated authentication, the contract’s URI must be the same on the identity 
provider and the service provider. For information about contract options, see Section 5.1.4, 
“Configuring Authentication Contracts,” on page 379. 


Most third-party identity providers do not use contracts. 
4 Configure the options: 


Response protocol binding: Select Artifact or Post or None. Artifact and Post are the two 
methods for transmitting assertions between the authenticating system and the target system. 


If you select None, you are letting the identity provider determine the binding. 
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Identity Provider proxy redirects: Specifies whether the trusted identity provider can proxy the 
authentication request to another identity provider. A value of None specifies that the trusted 
identity provider cannot redirect an authentication request. Values 1-5 determine the number of 
times the request can be proxied. Select Configured on IDP to let the trusted identity provider 
decide how many times the request can be proxied. 


Force authentication at Identity Provider: Specifies that the trusted identity provider must 
prompt users for authentication, even if they are already logged in. 


Use automatic introduction: Attempts single sign-on to this trusted identity provider by 
automatically sending a passive authentication request to the identity provider. (A passive 
requests does not prompt for credentials.) The identity provider sends one of the following 
authentication responses: 


+ When the federated user is authenticated at the identity provider: The identity provider 
returns an authentication response indicating that the user is authenticated. The user gains 
access to the service provider without entering credentials (single sign-on). 


+ When the federated user is not authenticated at the identity provider: The identity 
provider returns an authentication response indicating that the user is not logged in. The 
user can then select a card for authentication, including the card for the identity provider. If 
the user selects the identity provider card, an authentication request is sent to the identity 
provider. If the credentials are valid, the user is also authenticated to the service provider. 


IMPORTANT: Enable the Use automatic introduction option only when you are confident the 
identity provider will be up. If the server is down and does not respond to the authentication 
request, the user gets a page-cannot-be-displayed error. Local authentication is disabled 
because the browser is never redirected to the login page. 


This option must be enabled only when you know the identity provider is available 99.999% of 
the time or when the service provider is dependent upon this identity provider for authentication. 


5 Click OK twice, then update Identity Server. 


Configuring the Liberty Authentication Response 


After you create a trusted service provider, you can configure how your Identity Server responds to 
authentication requests from the service provider. 


1 Click Devices > Identity Servers > Edit > Liberty > [Service Provider] > Authentication 


Response. 
Select the binding method. 


If the request from the service provider does not specify a response binding, you need to specify 
a binding method to use in the response. Select Artifact to provide an increased level of security 
by using a back-channel means of communication between the two servers. Select Post to use 
HTTP redirection for the communication channel between the two servers. If you select Post, 
you might want to require the signing of the authentication requests. See “Configuring the 
General Identity Provider Settings” on page 177. 


Specify the identity formats that Identity Server can send in its response. Select the Use box to 
choose one or more of the following: 


+ Persistent Identifier Format: Specifies a persistent identifier that federates the user profile 
on the identity provider with the user profile on the service provider. It remains intact 
between sessions. 


¢ Transient Identifier Format: Specifies that a transient identifier, which expires between 
sessions, can be sent. 
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If the request from the service provider requests a format that is not enabled, the user cannot 
authenticate. 


4 Use the Default button to specify whether a persistent or transient identifier is sent when the 
request from the service provider does not specify a format. 


5 To specify that this Identity Server must authenticate the user, disable the Use proxied requests 
option. When the option is disabled and Identity Server cannot authenticate the user, the user is 
denied access. 


When this option is enabled, Identity Server checks to see if other identity providers can satisfy 
the request. If one or more can, the user is allowed to select which identity provider performs the 
authentication. If a proxied identity provider performs the authentication, it sends the response to 
Identity Server. Identity Server then sends the response to the service provider. 


6 Enable the Provide Discovery Services option if you want to allow the service provider to query 
Identity Server for a list of its Web Services. For example, when the option is enabled, the 
service provider can determine whether the Web Services Framework is enabled and which 
Web Service Provider profiles are enabled. 


7 Click OK twice, then update Identity Server. 


5.2.6.8 Defining Options for Liberty Service Provider 


Access Manager can be used as an identity provider for several service providers. You can configure 
a specific authentication contract that is required for a Service provider. If more than one 
authentication contract is configured for a service provider, the contract having minimum level will be 
selected. 


When providing authentication to a service provider, Identity Server ensures that the user is 
authenticated by the required contract. When a user is not authenticated or when user is 
authenticated, but the authenticated contracts do not satisfy the required contracts, user will be 
prompted to authenticate with required contract. This is called step up authentication. 


If no required contract is configured, then the default contract is executed. 


NOTE: This step up authentication is supported only for Intersite Transfer Service (identity provider 
initiated) requests on Liberty and works for both identity and service provider initiated requests for 
SAML 2.0. 


To Define Options for Liberty Service Provider 


1 Click Devices > Identity Servers > Servers > Edit > Liberty > Service Provider > Options. 


2 Select the required step up authentication contracts from the Available contracts list and move 
them to the Selected contracts list. This is to provide the step up authentication for the service 
provider. 


3 Click OK. 


5.2.6.9 Defining Options for Liberty Identity Provider 
1 Click Devices > Identity Servers > Servers > Edit > Liberty or SAML 2.0 > Identity Provider > 
Options. 


2 Enable Front Channel Logout: After this option is enabled, a service provider initiates a logout 
at the identity provider by using the HTTP Redirect method. 


3 Configure Front Channel Logout for Access Gateway Initiated Logout: In addition to 
enabling the front channel logout, configure the following property and restart tomcat: 


Configuring Authentication 515 


5.2.6.10 


5.2.6.11 


5.2.7 


Click Devices > Access Gateways > Edit > Reverse Proxy /Authentication > ESP Global 
Options. Remove the pound (#) symbol before forceESPSLOHTTP and set its value as true. 


Restart Tomcat: 

Linux: Enter the following command:/etc/init.d/novell-idp restart 
Windows: Enter the following commands: 

net stop Tomcat7 


net start Tomcat? 


Configuring the Session Timeout 


See “Configuring the Liberty or SAML 2.0 Session Timeout” on page 492. 


Modifying the Authentication Card 


See “Modifying the Authentication Card for Liberty or SAML 2.0” on page 492. 


Configuring Liberty Web Services 


A Web service uses Internet protocols to provide a service. It is an XML-based protocol transported 
over SOAP, or a service whose instances and data objects are addressable via URIs. 


Access Manager consists of several elements that comprise Web services: 


+ 


Web Service Framework: Manages all Web services. The framework defines SOAP header 
blocks and processing rules that enable identity services to be invoked via SOAP requests and 
responses. 


Web Service Provider: An entity that provides data via a Web service. In Access Manager, 
Web service providers host Web service profiles, such as the Employee Profile, Credential 
Profile, Personal Profile, and so on. 


Web Service Consumer: An entity that uses a Web service to access data. Web service 
consumers discover resources at the Web service provider, and then retrieve or update 
information about a user, or on behalf of a user. Resource discovery among trusted partners is 
necessary because a user might have many kinds of identities (employee, spouse, parent, 
member of a group), as well as several identity providers (employers or other commercial Web 
sites). 


Discovery Service: The service assigned to an identity provider that enables a Web Service 
Consumer to determine which Web service provider provides the required resource. 


LDAP Attribute Mapping: Access Manager's solution for mapping Liberty attributes with 
established LDAP attributes. 


This section describes the following topics: 


Section 5.2.7.1, “Web Services Framework,” on page 517 

Section 5.2.7.2, “Managing Web Services and Profiles,” on page 517 

Section 5.2.7.3, “Configuring Credential Profile Security and Display Settings,” on page 523 
Section 5.2.7.4, “Customizing Attribute Names,” on page 525 

Section 5.2.7.5, “Configuring the Web Service Consumer,” on page 525 

Section 5.2.7.6, “Mapping LDAP and Liberty Attributes,” on page 526 
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5.2.7.1 


5.2.7.2 


For additional resources about the Liberty Alliance specifications, visit the Liberty Alliance 
Specification (http://www.projectliberty.org/resources/specifications.php) page. 


Web Services Framework 


The Web Services Framework page lets you edit and manage all the details that pertain to all Web 
services. This includes the framework for building interoperable identity services, permission-based 
attribute sharing, identity service description and discovery, and the associated security mechanisms. 
1 Click Devices > Identity Servers > Edit > Liberty > Web Service Framework. 
2 Fill in the following fields: 
Enable Framework: Enables Web Services Framework. 


Axis SOAP Engine Settings: Axis is the SOAP engine that handles all Web service requests 
and responses. Web services are deployed using XML-based files known as Web service 
deployment descriptors (WSDD). On startup, Access Manager automatically creates the server- 
side and client-side configuration for Axis to handle all enabled Web services. 


If you need to override this default configuration, use the Axis Server Configuration WSDD XML 
field and the Axis Client Configuration WSDD XML field to enter valid WSDD XML. If either or 
both of these controls contain valid XML, then Access Manager does not automatically create 
the configuration (server or client) on startup. 


3 Click OK. 


Managing Web Services and Profiles 


After a service has been discovered and data has been received from a trusted identity provider, the 
Web service consumer can invoke the service at the Web service provider. A Web service provider is 
the hosting or relying entity on the server side that can make access control decisions based on this 
data and upon its business practices and preferences. 


1 In Administration Console Dashboard click Identity Servers > Edit > Liberty > Web Service 
Provider. 
2 Select one of the following actions 


New: To create a new Web service, click New. This activates the Create Web Service Wizard. 
You can create a new profile only if you have deleted one. 


Delete: To delete an existing profile, select the profile, then click Delete. 
Enable: To enable a profile, select the profile, then click Enable. 
Disable: To disable a profile, select the profile, then click Disable. 


Edit a Policy: To edit the policy associated with a profile, click the Policy link. For configuration 
information, see “Editing Web Service Policies” on page 521. 


Edit a profile: To edit a profile, click the name of a profile. For information about configuring the 
details, see “Modifying Service and Profile Details for Employee, Custom, and Personal 
Profiles” on page 518 and “Modifying Details for Authentication, Discovery, LDAP, and User 
Interaction Profiles” on page 520. 


For information about modifying the description, see “Editing Web Service Descriptions” on 
page 520. 


Identity Server comes with the following Web service profile types: 
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Authentication Profile: Allows the system to access the roles and authentication contracts in 
use by current authentications. This profile is enabled by default so that Embedded Service 
Providers can evaluate roles in policies. This profile can be disabled. When it is disabled, all 
devices assigned to use this Identity Server cluster configuration cannot determine which roles a 
user has been assigned, and the devices evaluate policies as if the user has no roles. 


WARNING: Do not delete this profile. In normal circumstances, this profile is used only by the 
system. 


Credential Profile: Allows users to define information to keep secret. It uses encryption to store 
the data in the directory the user profile resides in. 


Custom Profile: Used to create custom attributes for general use. 


Discovery: Allows requesters to discover where the resources they need are located. Entities 
can place resource offerings in a discovery resource, allowing other entities to discover them. 
Resources might be a personal profile, a calendar, travel preferences, and so on. 


Employee Profile: Allows you to manage employment-related information and how the 
information is shared with others. A company address book that provides names, phones, office 
locations, and so on, is an example of an employee profile. 


LDAP Profile: Allows you to use LDAP attributes for and general use. 


Personal Profile: Allows you to manage personal information and to determine how to share 
that information with others. A shopping portal that manages the user’s account number is an 
example of a personal profile. 


User Interaction: Allows you to set up a trusted user interaction service, used for identity 
services that must interact with the resource owner to get information or permission to share 
data with another Web service consumer. This profile enables a Web service consumer and Web 
service provider to cooperate in redirecting the resource owner to the Web service provider and 
back to the Web service consumer. 

3 Click OK. 


4 On the Servers page, update Identity Server. 


Modifying Service and Profile Details for Employee, Custom, and Personal 
Profiles 


The settings on the Details page are identical for the Employee, Custom, and Personal Profiles. This 
page allows you to specify the display name, resource ID encryption, and how the system reads and 
writes data. 

1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 


2 Click Custom Profile, Employee Profile, or Personal Profile, depending on which profile you 
want to edit. 


3 Click the Details tab (it is displayed by default). 
4 Specify the general settings, as necessary: 


Display Name: The Web service name. This specifies how the profile is displayed in 
Administration Console. 


Have Discovery Encrypt This Service’s Resource Ids: Specifies whether the Discovery 
Service encrypts resource IDs. A resource ID is an identifier used by Web services to identify a 
user. The Discovery Service returns a list of resource IDs when a trusted service provider 
queries for the services owned by a given user. The Discovery Service has the option of 
encrypting the resource ID or sending it unencrypted. 


5 Specify data location settings: 
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Selected Read Locations: The list of selected locations from which the system reads attributes 
containing profile data. If you add multiple entries to this list, the system searches attributes in 
each location in the order you specify. When a match is found for an attribute, the other locations 
are not searched. Use the up/down and left/right arrows to control which locations are selected 
and the order in which to read them. Read locations can include: 


¢ Configuration Datastore: Liberty attribute values can be stored in the configuration store 
of Administration Console. If your users have access to the User Portal, they can add 
values to a number of Liberty attributes. 


+ LDAP Data Mappings: If you have mapped a Liberty attribute to an LDAP attribute in your 
user store, the values can be read from the LDAP user store. To create LDAP attribute 
maps, see “Mapping LDAP and Liberty Attributes” on page 526. 


+ Remote Attributes: If you set up federation, Identity Server can read attributes from these 
remote service providers. Sometimes, the service provider is set up to push a set of 
attribute values when the user logs in. These pushed attributes are cached, and Identity 
Server can quickly read them. If a requested attribute has not been pushed, a request for 
the Liberty attribute is sent to remote service provider. This can be time consuming, 
especially if the user has federated with more than one remote service provider. Remote 
Attributes must always be the last item in this list. 


Available Read Locations: The list of available locations from which the system can read 
attributes containing profile data. Locations in this list are currently not being used. 


Selected Write Locations: The list of selected locations to write attribute data to. If you add 
multiple entries to this list, the system searches attributes in each location in the order you 
specify. When a match is found for an attribute, the other locations are not searched. Use the up/ 
down and left/right arrows to control which locations are selected and the order in which they are 
selected. 


¢ Configuration Datastore: Liberty attribute values can be stored in the configuration store 
of Administration Console. Identity Server can write values to these attributes. If this 
location appears first in the list of Selected Write Locations, all Liberty attribute values are 
written to this location. If you want values written to the LDAP user store, the LDAP Data 
Mappings location must appear first in the list. 


+ LDAP Data Mappings: If you have mapped a Liberty attribute to an LDAP attribute in your 
user store, Identity Server can write values to the attribute in the LDAP user store. To create 
LDAP attribute maps, see “Mapping LDAP and Liberty Attributes” on page 526. 


Available Write Locations: The list of available locations to write attributes containing profile 
data. Locations in this list are currently not being used. 


6 (Optional) Specify data model extensions. 


Data Model Extension XML: The data model for some Web services is extensible. You can 
enter XML definitions of data model extensions in this field. Data model extensions hook into the 
existing Web service data model at predefined locations. 


All schema model extensions reside inside of a schema model extension group. The group 
exists to bind model data items together under a single localized group name and description. 
Schema model extension groups can reside inside of a schema model extension root or inside of 
a schema model extension. There can only be one group per root or extension. Each root is 
hooked into the existing Web service data model. Multiple roots can be hooked into the same 
location in the existing Web service data model. This conceptual model applies to the structure 
of the XML that is required to define data model extensions. 


See Appendix A, “Data Model Extension XML,” on page 1461 for more information. 
7 Click OK, then click OK on the Web Service Provider page. 
8 Update Identity Server. 
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Modifying Details for Authentication, Discovery, LDAP, and User Interaction 
Profiles 


This page allows you to specify information for Discovery, LDAP, and User Interaction Web service 
profiles. If you are creating a Web service type, this is Step 2 of the Create Web Service Wizard. 


For conceptual information about profiles, see Managing Web Services and Profiles. 


1 Click Devices> Identity Servers > Edit > Liberty > Web Service Provider > [Profile]. 


2 Click Authentication, Discovery, LDAP, or User Interaction, depending on which profile you want 
to edit. 


3 Configure the following fields: 


Display name: The Web service name. This specifies how the profile is displayed in 
Administration Console. 


Have Discovery Encrypt This Service’s Resource Ids: (Not applicable for the Discovery 
profile) Specifies whether the Discovery Service encrypts resource IDs. A resource ID is an 
identifier used by Web services to identify a user. The Discovery Service returns a list of 
resource IDs when a trusted service provider queries for the services owned by a given user. 
The Discovery Service has the option of encrypting the resource ID or sending it unencrypted. 
This ID is encrypted with the public key of the resource provider generated at installation. 
Encrypting resource IDs is turned off by default. 


4 Click OK. 


Editing Web Service Descriptions 


All of the Description pages on each profile are identical. You can define how a service provider gains 
access to portions of the user's identity information that can be distributed across multiple providers. 
The service provider uses the Discovery Service to ascertain the location of a specific identity service 
for a user. The Discovery Service enables various entities to dynamically and securely discover a 
user's identity service, and it responds, on a permission basis, with a service description of the 
desired identity service. 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 
2 Click the profile or service. 
3 Click Descriptions. 
4 Click the description name, or click New. 
5 Fill in the following fields: 
Name: The Web Service Description name. 


Security Mechanism: (Required) Liberty uses channel security (TLS 1.0) and message security 
in conjunction with the security mechanism. Channel security addresses how communication 
between identity providers, service providers, and user agents is protected. For authentication, 
service providers are required to authenticate identity providers by using identity provider server- 
side certificates. Identity providers have the option to require authentication of service providers 
by using service provider client-side certificates. 


Message security addresses security mechanisms applied to the discrete Liberty protocol 
messages passed between identity providers, service providers, and user agents. 


Select the mechanism for message security. Message authentication mechanisms indicate 
which profile is used to ensure the authenticity of a message. 


+ X.509: Used for message exchanges that generally rely upon message authentication as 
the principle factor in making decisions. 
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+ SAML: Used for message exchanges that generally rely upon message authentication as 
well as the conveyance and attestation of information. 

+ Bearer: Based on the presence of the security header of a message. In this case, the 
bearer token is verified for authenticity rather than proving the authenticity of the message. 


Under Select Service Access Method, select either Brief Service Access Method or WSDL 
Service Access Method. 


Brief Service Access Method: Provides the information necessary to invoke basic SOAP-over- 
HTTP-based service instances without using WSDL. 

+ EndPoint URL: This is the SOAP endpoint location at the service provider to which Liberty 
SOAP messages are sent. An example of this for the Employee Profile is [BASEURL]/ 
services/IDSISEmployeeProfile. If the service instance exposes an endpoint that is different 
from the logically generated concrete WSDL, you must use the WSDL URI instead. 


A WSF service description endpoint cannot contain double-byte characters. 


+ SOAP Action: The SOAP action HTTP header required on HTTP-bound SOAP messages. 
This header can be used to indicate the intent of a SOAP message to the recipient. 


WSDL Service Access Method: Specify the method used to access the WSDL service. WSDL 
(Web Service Description Language) describes the interface of a Web service. 

+ Service Name Reference: A reference name for the service. 

+ WSDL URI: Provides a URI to an external concrete WSDL resource containing the service 


description. URIs need to be constant across all implementations of a service to enable 
interoperability. 


7 Click OK. 
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Update Identity Server configuration. 


Editing Web Service Policies 


Web Service policies are permission policies (query and modify) that govern how identity providers 
share end-user data with service providers. Administrators and policy owners (users) can control 
whether private information is always allowed to be given, never allowed, or must be requested. 


As an administrator, you can configure this information for the policy owner, for specific service 
providers, or globally for all service providers. You can also specify what policies are displayed for the 
end user in the User Portal, and whether users are allowed to edit them. 


1 
2 
3 


Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 
Click the Policy link next to the service name. 
Click the category you want to edit. 


All Trusted Providers: Policies that are defined by the service provider's ability to query and 
modify the particular Liberty attributes or groups of attributes for the Web service. When All 
Trusted Providers permissions are established, and a service provider needs data, the system 
first looks here to determine whether user data is allowed, never allowed, or must be asked for. If 
no solution is found in All Trusted Providers, the system examines the permissions established 
within the specific service provider. 


Owners: Policies that limit the end user’s ability to modify or query data from his or her own 
profile. The settings you specify in the Owner group are reflected on the My Profile page in the 
User Portal. Portal users have the authority to modify the data items in their profiles. The data 
items include Liberty and LDAP attributes for personal identity, employment, and any customized 
attributes defined in Identity Server configuration. Any settings you specify in Administration 
Console override what is displayed in the User Portal. Overrides are displayed in the Inherited 
column. 
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If you want the user to have Write permission for a given data item, and that data item is used in 
an LDAP Attribute Map, then you must configure the LDAP Attribute Map with Write permission. 


On the All Service Policy page, select the policy’s check box, then click Edit Policy. 


This lets you modify the parent service policy attribute. Any selections you specify on this page 

are inherited by child policies. 

Query Policy: Allows the service provider to query for the data on a particular attribute. This is 

similar to read access to a particular piece of data. 

Modify Policy: Allows the service provider to modify a particular attribute. This is similar to write 
access to a particular piece of data. 

Query and Modify: Allows you to set both options at once. 

To edit child attributes of the parent, click the policy. 

In the following example, child attributes are inheriting Ask Me permission from the parent Entire 


Personal Identity attribute. The Postal Address attribute, however, is modified to never allow 
permission for sharing. 


If you click the Postal Address attribute, you can see that all of its child attributes have inherited 
the Never Allow setting. You can specify different permission attributes for Address Type (for 
example), but the inherited policy still overrides changes made at the child level, as shown 
below. 


Postal Addresses 


Postal Addresses 


Edit Policy 6 Itemfs) 
[ Policy Query Policy Modify Policy Inherited 

l Address Type Always Allow Always Allow Never Allow : Never Allow 

I~ NickName Ask Me Ask Me Never Allow : Never Allow 

I~ Localized NickNames Ask Me Ask Me Never Allow : Never Allow 

Comment Ask Me Ask Me Never Allow : Never Allow 

I~ Postal Address Ask Me Ask Me Never Allow : Never Allow 

I~ Postal Addresses Extensions Ask Me Ask Me Never Allow : Never Allow 


The interface allows these changes to simplify switching between configurations if, for example, 
you want to remove an inherited policy. 


Inherited: Specifies the settings inherited from the parent attribute policy, when you view a child 
attribute. In the User Portal, settings displayed under Inherited are not modifiable by the user. At 
the top-level policy in the User Portal, the values are inherited from the settings in Administration 
Console. Thereafter, inheritance can come from the service policy or the parent data item’s 
policy. 

Ask Me: Specifies that the service provider requests from the user what action to take. 


Always Allow: Specifies that the identity provider always allows the attribute data to be sent to 
the service provider. 


Never Allow: Specifies that the identity provider never allows the attribute data to be sent to the 
service provider. 


When a request for data is received, Identity Server examines policies to determine what action 
to take. For example, if a service provider requires a postal address for the user, Identity Server 
performs the following actions: 


+ Checks the settings specified in All Service Providers. 
+ If no solution is found, checks for the policy settings configured for the service provider. 
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6 Click OK until the Web Service Provider page is displayed. 
7 Click OK, then update Identity Server as prompted. 


Create Web Service Type 


This page allows you to create a Web service profile type. This is Step 1 of the Create Web Service 
Wizard. Access Manager comes with several Web service profiles, but if you have deleted a profile 
type, you can create it again. 

1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider > New. 

2 Select the Web service type from the drop-down list, then click Next. 

3 Continue with one of the following: 


¢ “Modifying Service and Profile Details for Employee, Custom, and Personal Profiles” on 
page 518. 


¢ “Modifying Details for Authentication, Discovery, LDAP, and User Interaction Profiles” on 
page 520. 


Configuring Credential Profile Security and Display Settings 


On the Credential Profile Details page, you can specify whether this profile is displayed for end users, 
and determine how you control and store encrypted secrets. You can store and access secrets 
locally, on remote eDirectory servers that are running Novell SecretStore, or on a user store that has 
been configured with a custom attribute for secrets. 


For more information about storing encrypted secrets, see the following: 
¢ For information about how to configure Access Manager for secrets, see “Configuring a User 
Store for Secrets” on page 364. 


+ For general information about Novell SecretStore, see the Novell SecretStore Administration 
Guide (http://www.novell.com/documentation/secretstore33/pdfdoc/nssadm/nssadm.pdpf). 


+ For information about creating shared secrets for Form Fill and Identity Injection policies, see 
Section 8.5.4, “Creating and Managing Shared Secrets,” on page 853. 
To configure the Credential Profile: 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Providers. 

2 Click Credential Profile. 

3 On the Credential Profile Details page, fill in the following fields as necessary: 
Display name: The name you want to display for the Web service. 


Have Discovery Encrypt This Service’s Resource Ids: Specify whether the Discovery 
Service encrypts the resource IDs. A resource ID is an identifier used by Web services to identify 
a user. The Discovery Service returns a list of resource IDs when a trusted service provider 
queries for the services owned by a given user. The Discovery Service has the option of 
encrypting the resource ID or sending it unencrypted. Encrypting resource IDs is disabled by 
default. 


4 Under Credential Profile Settings, enable the following option if necessary: 


Allow End Users to See Credential Profile: Specify whether to display or hide the Credential 
Profile in the Access Manager User Portal. Profiles are viewed on the My Profile page, where the 
user can modify his or her profile. 


5 Specify how you want to control and store secrets: 
5a To locally control and store secrets, configure the following fields: 


Configuring Authentication 523 


524 


Encryption Password Hash Key: (Required) Specify the password that you want to use 
as a seed to create the encryption algorithm. To increase the security of the secrets, ensure 
that you change the default password to a unique alphanumeric value. 


Preferred Encryption Method: Specify the preferred encryption method. Select the 
method that complies with your security model: 


¢ Password Based Encryption With MD5 and DES: MD5 is an algorithm that is used 
to verify data integrity. Data Encryption Standard (DES) is a widely used method of 
data encryption that uses a private key. 


¢ DES: Data Encryption Standard (DES) is a widely used method of data encryption that 
uses a private key. Like other private key cryptographic methods, both the sender and 
the receiver must know and use the same private key. 


¢ Triple DES: A variant of DES in which data is encrypted three times with standard DES 
by using two different keys. 


5b Specify where to store secret data. (For more information about setting up a user store for 
secret store, see “Configuring a User Store for Secrets” on page 364.) 


+ To have the secrets stored in the configuration database, do not configure the list in the 
Extended Schema User Store References section. You only need to configure the 
fields in Step 5a. 


+ To store the secrets in your LDAP user store, click New in Extended Schema User 
Store References and configure the following fields: 


User Store: Select a user store where secret data is stored. 


Attribute Name: Specify the LDAP attribute of the User object that can be used to 
store the secrets. When a user authenticates by using the user store specified here, 
the secret data is stored in an XML document of the specified attribute of the user 
object. This attribute must be a single-valued case ignore string that you have defined 
and assigned to the user object in the schema. 


NOTE: Do not use this LDAP attribute in Policy configuration as shared secrets. 
Instead you create the shared secrets attributes. The Shared secret attributes are 
populated in the configured LDAP attribute, and are used by policy for mapping. For 
more information about how to create shared secret, see Chapter 8.5, “Form Fill 
Policies,” on page 831. 


+ To use Novell SecretStore to remotely store secrets, click New under Novell Secret 
Store User Store References. 


Click the user store that you have configured for SecretStore. 


Secure LDAP must be enabled between the user store and Identity Server to add this 
user store reference. 


5c Click OK twice. 
6 On Identity Server page, update Identity Server. 
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Customizing Attribute Names 


You can change the display names of the attributes for the Credential, Custom, Employee, and 
Personal profiles. The customized names are displayed on the My Profile page in the User Portal. 
The users see the custom names applicable to their language. Custom Attributes are displayed on 
the My Profile page in the User Portal in place of the corresponding English attribute name when the 
language in the drop-down list is the accepted language of the browser. 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider > [Profile] > Custom 
Attribute Names. 

Click the data item name to view the customized attribute names. 

Click New to create a new custom name. 

Type the name and select a language. 

Click OK. 

On the Custom Attribute Names page, click OK. 

On the Web Service Provider page, click OK. 
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Update Identity Server configuration on the Servers page. 


Configuring the Web Service Consumer 


The Web service consumer is the component within the identity provider that requests attributes from 
Web service providers. The identity provider and Web services consumer cooperate to redirect the 
user or resource owner to the identity provider, allowing interaction. You can configure an interaction 
service, which allows the identity provider to pose simple questions to a user. This service can be 
offered by trusted Web services consumers, or by a dedicated interaction service provider that has a 
reliable means of communication with the users. 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Consumers 
The following general settings configure time limits and processing speed: 
Protocol Timeout (seconds): Limits the time the transport protocol allows. 


Provider Timeout (seconds): Limits the request processing at the Web service provider. This 
value must always be equal to or greater than the Protocol Timeout value. 


Attribute Cache Enabled: A subsystem of the Web service consumer that caches attribute data 
that the Web service consumer requests. For example, if the Web service consumer has already 
requested a first name attribute from a Web service provider, the Web service consumer does 
not need to request the attribute again. This setting improves performance when enabled. 
However, you can disable this option to increase system memory. 


2 Specify how and when the identity provider interacts with the user: 


Always Allow Interaction: Allows interaction to take place between users and service 
providers. 


Never Allow Interaction: Never allows interaction between users and service providers. 


Always Allow Interaction for Permissions, Never for Data: Allows interaction for 
permissions, never for data. 


Maximum Allowed Interaction Time: Specifies the allowed time (in seconds). 


3 To specify the allowable methods that a Web service provider can use for user interaction, click 
one of the following options: 
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Redirect to a User Interaction Service: Allows the Web service consumer to redirect the user 
agent to the Web service provider to ask questions. After the Web service provider has obtained 
the information it needs, it can redirect the user back to the Web service consumer. 


Call a Trusted User Interaction Service: Allows the Web service provider to trust the Web 
service consumer to act as proxy for the resource owner. 


Under Security Settings, fill in the following fields: 


WSS Security Token Type: Instructs the Web service consumer/requestor how to place the 
token in the security header as outlined in the Liberty ID-WSF Security Mechanisms. 


Signature Algorithm: The signature algorithm to use for signing the payload. 


5 Click OK, then update Identity Server configuration as prompted. 


Mapping LDAP and Liberty Attributes 


You can create an LDAP attribute map or edit an existing one. To create an attribute map, you specify 
how single-value and multi-value data items map to single-value and multi-value LDAP attributes. A 
single-value attribute can contain no more than one value, and a multi-value attribute can contain 
more than one. An example of a single-value attribute might be a person’s gender, and an example of 
a multi-value attribute might be a person’s various e-mail addresses, phone numbers, or titles. 


1 Click Devices> Identity Servers > Edit > Liberty >LDAP Attribute Mapping. 
2 Select one of the following actions: 


New: Allows you create an LDAP attribute mapping. Select from the following types: 
+ One to One: Maps a single Liberty attribute to a single LDAP attribute. See “Configuring 
One-to-One Attribute Maps” on page 527. 


+ Employee Type: Maps the Employee Type attribute to an LDAP attribute, then maps the 
possible Liberty values to LDAP values. See “Configuring Employee Type Attribute Maps” 
on page 531. 


+ Employee Status: Maps the Employee Status attribute to an LDAP attribute, then maps 
the possible Liberty values to LDAP values. See “Configuring Employee Status Attribute 
Maps” on page 531. 


+ Postal Address: Maps the Postal Address attribute to either multiple LDAP attributes or a 
delimited LDAP attribute. See “Configuring Postal Address Attribute Maps” on page 532. 


+ Contact Method: Maps the Contact Method attribute to multiple LDAP attributes. See 
“Configuring Contact Method Attribute Maps” on page 533. 


+ Gender: Maps the Gender attribute to an LDAP attribute, then maps the possible Liberty 
values to LDAP values. See “Configuring Gender Attribute Maps” on page 534. 


+ Marital Status: Maps the Marital Status attribute to an LDAP attribute, then maps the 
possible Liberty values to LDAP values. See “Configuring Marital Status Attribute Maps” on 
page 534. 


Delete: Deletes the selected mapping. 
Enable: Enables the selected mapping. 


Disable: Disables the selected mapping. When the mapping is disabled, the server does not 
load the definition. However, the definition is not deleted. 


3 Click OK, then update Identity Server. 
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Configuring One-to-One Attribute Maps 


A one-to-one map enables you to map single-value and multiple-value LDAP attribute names to 


standard Liberty attributes. A default one-to-one attribute map is provided with Access Manager, but 


you can also define your own. 


An example of a one-to-one attribute map might be the single-valued Liberty attribute Common Name 
(CommonName) used by the Personal Profile that is mapped to the LDAP attribute givenName. You 


can further configure the various Liberty values to map to any LDAP attribute names that you use. 


1 Click Devices > Identity Servers > Edit > Liberty > LDAP Attribute Mapping > New > One to 


One. 
2 Configure the following fields: 
Type: Displays the type of mapping you are modifying or creating: 
Name: The name you want to give the map. 
Description: A description of the map. 


Access Rights: A drop-down menu that provides the broadest control for the page. If you set 


this to Read/Write, you can specify rights for individual data items. 


For user provisioning to succeed, you must select Read/Write from the Access Rights drop- 


down menu for any maps that use an attribute during user provisioning. 


User Stores: The user store that a map applies to. If a user logs into a user store that is not in 


the map’s user store list, that map is not used to read or write attributes for that user. 
3 Use the following guidelines to configure the map: 
¢ Mapping Personal Profile Single-Value Data Items to LDAP Attributes 
+ Mapping Personal Profile Multiple-Value Data Items to LDAP Attributes 
¢ Mapping Employee Profile Single-Value Data Items to LDAP Attributes 
+ Mapping Employee Profile Multiple-Value Data Items to LDAP Attributes 
+ Mapping Custom Profile Single-Value Data Items to LDAP Attributes 
+ Mapping Custom Profile Multiple-Value Data Items to LDAP Attributes 
4 After you create the mapping, click Finish. 
5 On the LDAP Attribute Mapping page, click OK. 
6 Update Identity Server. 
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Mapping Personal Profile Single-Value Data Items to LDAP Attributes 


The data items displayed are single-value Liberty Personal Profile attributes that you can map to the 


single-valued LDAP attributes that you have defined for your directory. 


Default One-To-One Ldap Attribute Mapping 


Personal Profile Single Valued Data Items to LDAP Attributes 


Data Item Name: 
Informal Name 

Every Day Name 
Common Personal Title 
Common First Name 
Common Last Name 
Common Middle Name 
Legal Name 

Legal Personal Title 
Legal First Name 

Legal Last Name 

Legal Middle Name 
Legal Fiscal Identification Type 


Legal Fiscal Identification Value 


— Ok | Cancel | 
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Ldap Attribute Name: 


Access Rights: 


ffullName 
[title | Read Only z] 
[givenName | Read Only z] 


| Read Only v 


ReadOnly v 


Mapping Personal Profile Multiple-Value Data Items to LDAP Attributes 


Use the fields on this page to map multiple-value attributes from the Liberty Personal Profile to the 
multiple-value LDAP attributes you have defined for your directory. For example, you can map the 
Liberty attribute Alternate Every Day Name (AItCN) to the LDAP attribute you have defined for this 
purpose in your directory. 


Default One-To-One Ldap Attribute Mapping 


Personal Profile Multiple Valued Data Items to LDAP Attributes 
Data Item Name: Ldap Attribute Name: Access Rights: 
Alternate Every Day Name 


Alternate Department Names | 
Spoken or Understood Languages | 


Employee Profile Single Valued Data Items to LDAP Attributes 
Data Item Name: Ldap Attribute Name: Access Rights: 
Id 


Date of Hire 
Job Start Date 


Status 


Type 
Internal Job Title 


Department 


OK | Cancel | 


Mapping Employee Profile Single-Value Data Items to LDAP Attributes 


Map the Liberty Employee Profile single-value attributes to the LDAP attributes you have defined in 
your directory for entries such as ID, Date of Hire, Job Start Date, Department, and so on. 


Mapping Employee Profile Multiple-Value Data Items to LDAP Attributes 


Map the Liberty Employee Profile multiple-value attributes to the LDAP attributes you have defined in 
your directory. 
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Mapping Custom Profile Single-Value Data Items to LDAP Attributes 
Map custom Liberty profile single-value attributes to LDAP attributes you have defined in your 
directory. These attributes are customizable strings associated with the Custom Profile. 


Default One-To-One Ldap Attribute Mapping 


Custom Profile Single Valued Data Items to LDAP Attributes 
Data Item Name: Ldap Attribute Name: Access Rights: 


Customizable String One fF 
Customizable String Two ee 
Customizable String Three FO 
Customizable String Four fF 
Customizable String Five fC 
Customizable String Six FO 
Customizable String Seven FO 
Customizable String Eight P 
Customizable String Nine P 
Customizable String Ten P 


Custom Profile Multiple Valued Data Items to LDAP Attributes 


Daa ARR 
Read Only 


Data Item Name: Ldap Attribute Name: Access Rights: 


Customizable Wulti-Valued Strings One | 
Customizable Multi-Valued Strings Two | 


Customizable String (1 - 10): The Custom Profile allows custom single-value and multiple-value 
attributes to be defined without using the Data Model Extension XML to extend a service’s schema. 
To use a customizable attribute, navigate to the Custom Attribute Names tab on the Custom Profile 
Details page (see “Customizing Attribute Names” on page 525). Use the page to customize the name 
of any of the predefined single-value or multiple-value customizable attributes in the Custom Profile. 
After you customize a name, you can use that attribute in the same way you use any other profile 
attribute. 


Mapping Custom Profile Multiple-Value Data Items to LDAP Attributes 


Customizable Multi-Valued Strings (1 - 5): Similar to customizable strings for single-value 
attributes, except these attributes can have multiple values. Use this list of fields to map directory 
attributes that can have multiple values to multiple-value strings from the Custom Profile. 


530 Configuring Authentication 


Configuring Employee Type Attribute Maps 


You can map the LDAP attribute name and values to the Liberty profile values for Employee Type. 
This is an Employee Profile attribute. Examples of Liberty values appended to this attribute include 
Contractor Part Time, Contractor Full Time, Full Time Regular, and so on. 


1 Click Devices > Identity Servers > Edit > Liberty > LDAP Attribute Mapping > New > Employee 
Type. 

2 Configure the following fields: 
Name: The name you want to give the map. 
Description: A description of the map. 


Access Rights: A drop-down menu that provide the broadest control for the page. If you set this 
to Read/Write, you can specify rights for individual data items. 


For user provisioning to succeed, you must select Read/Write from the Access Rights drop- 
down menu for any maps that use an attribute during user provisioning. 


User Stores: The user store that a map applies to. If a user logs into a user store that is not in 
the map’s user store list, that map is not used to read or write attributes for that user. 


3 In the LDAP Attribute Name field, type the LDAP attribute name that you want to map to the 
Liberty Employee Type attribute. 


4 In the LDAP Attribute Value fields, type the predefined LDAP attribute values that you want to 
map to the Liberty Employee Type values. 


These are the values that you want to store in the LDAP attribute for each given Liberty attribute 
value. The LDAP attribute map then maps the actual Liberty URI value, back and forth, to this 
supplied value. 


5 Click Finish. 
6 On the LDAP Attribute Mapping page, click OK. 
7 Update Identity Server. 


Configuring Employee Status Attribute Maps 


You can map the LDAP attribute name and values to the Liberty profile values for Employee Status. 
This is an Employee Profile attribute. Examples of the values appended to this Liberty attribute 
include Active, Trial, Retired, Terminated, and so on. 


1 Click Devices > Identity Servers > Edit > Liberty > LDAP Attribute Mapping > New > Employee 
Status. 

2 Configure the following fields: 
Name: The name you want to give the map. 
Description: A description of the map. 


Access Rights: A drop-down menu that provide the broadest control for the page. If you set this 
to Read/Write, you can specify rights for individual data items. 


For user provisioning to succeed, you must select Read/Write from the Access Rights drop- 
down menu for any maps that use an attribute during user provisioning. 


User Stores: The user store that a map applies to. If a user logs into a user store that is not in 
the map’s user store list, that map is not used to read or write attributes for that user. 


3 In the LDAP Attribute Name field, type the LDAP attribute name that you want to map to the 
Liberty Employee Status element. 
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4 In the LDAP Attribute Value fields, type the predefined LDAP attribute values that you want to 
map to the Liberty Employee Status values. 


These are the values that you want to store in the LDAP attribute for each given Liberty attribute 
value. The LDAP attribute map then maps the actual Liberty URI value, back and forth, to this 
supplied value. 


5 Click Finish. 
6 On the LDAP Attribute Mapping page, click OK. 
7 Update Identity Server. 


Configuring Postal Address Attribute Maps 


You can map the LDAP attribute name and values to the Liberty profile values for Postal Address. 
The PostalAddress element refers to the local address, including street or block with a house number, 
and so on. This is a Personal Profile attribute. 


1 Click Devices > Identity Servers > Edit > Liberty > LDAP Attribute Mapping > New > Postal 
Address. 

2 Configure the following fields: 
Name: The name you want to give the map. 
Description: A description of the map. 


Access Rights: A drop-down menu that provide the broadest control for the page. If you set this 
to Read/Write, you can specify rights for individual data items. 


For user provisioning to succeed, you must select Read/Write from the Access Rights drop- 
down menu for any maps that use an attribute during user provisioning. 


User Stores: The user store that a map applies to. If a user logs into a user store that is not in 
the map’s user store list, that map is not used to read or write attributes for that user. 


3 In the Mode drop-down menu, select either Multiple LDAP Attributes or Single Delimited LDAP 
Attributes. 


Multiple LDAP Attributes: Allows you to map multiple LDAP attributes to multiple Liberty Postal 
Address elements. When you select this option, the following Liberty Postal Address elements 
are displayed under the Postal Address to LDAP Attributes group. Type the LDAP attributes 
that you want to map to the Liberty elements. 


+ Postal Address 
+ Postal Code 

+ City 

+ State 

+ Country 


Single Delimited LDAP Attributes: Allows you to specify one LDAP attribute that is used to 
hold multiple elements of a Liberty Postal Address in a single delimited value. When you select 
this option, the page displays the following fields: 
+ Delimited LDAP Attribute Name: The delimited LDAP attribute name you have defined for 
the LDAP postal address that you want to map to the Liberty Postal Address attribute. 


¢ Delimiter: The character to use to delimit single-value entries. A $ sign is the default 
delimiter. 


4 (Single Delimited LDAP Attributes mode) Under One-Based Field Position in Delimited LDAP 
Attribute, specify the order in which the information is contained in the string. Select 1 for the 
value that comes first in the string, 2 for the value that follows the first delimiter, etc. 
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5 (Multiple LDAP Attributes mode) Under Postal Address Template Data, fill in the following 
options: 


Nickname: (Required) A Liberty element name used to identify the Postal Address object. 


Contact Method Type: Select the contact method type, such as Domicile, Work, Emergency, 
and so on. 


6 Click Finish. 
7 On the LDAP Attribute Mapping page, click OK. 
8 Update Identity Server. 


Configuring Contact Method Attribute Maps 


You can map the LDAP attribute you have defined for contact methods to the Liberty attribute Contact 
Method (MsgContact). 


1 Click Devices > Identity Servers > Edit > Liberty > LDAP Attribute Mapping > New > Contact 
Method. 

2 Configure the following fields: 
Name: The name you want to give the map. 
Description: A description of the map. 


Access Rights: A drop-down menu that provide the broadest control for the page. If you set this 
to Read/Write, you can specify rights for individual data items. 


For user provisioning to succeed, you must select Read/Write from the Access Rights drop- 
down menu for any maps that use an attribute during user provisioning. 


User Stores: The user store that a map applies to. If a user logs into a user store that is not in 
the map’s user store list, that map is not used to read or write attributes for that user. 


3 Under Contact Method to LDAP Attributes, fill in the following fields to map to the Liberty 
Contact Method attribute: 


Provider LDAP Attribute: Maps to the Liberty attribute MsgProvider, which is the service 
provider or domain that provides the messaging service. 


Account LDAP Attribute: Maps to the Liberty attribute MsgAccount, which is the account or 
address information within the messaging provider. 


SubAccount LDAP Attribute: Maps to the Liberty MsgSubaccount, which is the subaccount 
within a messaging account, such as the voice mail box associated with a phone number. 


4 Under Contact Method Template Data, specify the settings for the following Liberty attribute 
values: 


Nickname: Maps to the Liberty attribute Nick, which is an informal name for the contact. 
Type: Maps to the Liberty attribute MsgType (such as Mobile, Personal, or Work). 
Method: Maps to the Liberty MsgMethod (such as Voice, Fax, or E-mail). 
Technology: Maps to the Liberty attribute MsgTechnology (such as Pager, VOIP, and so on). 
5 Click Finish. 
6 On the LDAP Attribute Mapping page, click OK. 
7 Update Identity Server. 
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Configuring Gender Attribute Maps 


You can map the LDAP attribute name and values to the Liberty profile values for the Gender 
attribute. You can use gender to differentiate between people with the same name, especially in 
countries where national ID numbers cannot be collected. This is a Personal Profile attribute. 
1 Click Devices > Identity Servers > Edit > Liberty > LDAP Attribute Mapping > New > Gender. 
2 Configure the following fields: 
Name: The name you want to give the map. 
Description: A description of the map. 


Access Rights: A drop-down menu that provide the broadest control for the page. If you set this 
to Read/Write, you can specify rights for individual data items. 


For user provisioning to succeed, you must select Read/Write from the Access Rights drop- 
down menu for any maps that use an attribute during user provisioning. 


User Stores: The user store that a map applies to. If a user logs into a user store that is not in 
the map’s user store list, that map is not used to read or write attributes for that user. 


3 In the LDAP Attribute Name field, type the LDAP attribute name that you want to map to the 
Liberty element Gender. 


4 In the LDAP Attribute Value fields, type the predefined LDAP attribute values that you want to 
map to the Gender values. 


These are the values that you want to store in the LDAP attribute for each given Liberty attribute 
value. The LDAP attribute map then maps the actual Liberty URI value, back and forth, to this 
supplied value. 


5 Click Finish. 
6 On the LDAP Attribute Mapping page, click OK. 
7 Update Identity Server. 


Configuring Marital Status Attribute Maps 


You can map the LDAP marital status attribute to the Liberty attribute. The Liberty Marital Status 
(MaritalStatus) element includes appended values such as single, married, divorced, and so on. For 
example, urn: liberty: id-sis-pp:maritalstatus: single. This is a Personal Profile attribute. 


1 Click Devices > Identity Servers > Edit > Liberty > LDAP Attribute Mapping > New > Marital 
Status. 

2 Configure the following fields: 
Name: The name you want to give the map. 
Description: A description of the map. 


Access Rights: A drop-down menu that provide the broadest control for the page. If you set this 
to Read/Write, you can specify rights for individual data items. 


For user provisioning to succeed, you must select Read/Write from the Access Rights drop- 
down menu for any maps that use an attribute during user provisioning. 


User Stores: The user store that a map applies to. If a user logs into a user store that is not in 
the map’s user store list, that map is not used to read or write attributes for that user. 


3 In the LDAP Attribute Name field, type the LDAP attribute name that you want to map to the 
Liberty element Marital Status (MaritalStatus). 


4 In the LDAP Attribute Value fields, type the predefined LDAP attribute values that you want to 
map to the MaritalStatus values. 
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These are the values that you want to store in the LDAP attribute for each given Liberty attribute 
value. The LDAP attribute map then maps the actual Liberty URI value, back and forth, to this 
supplied value. 


5 Click Finish. 
6 On the LDAP Attribute Mapping page, click OK. 
7 Update Identity Server. 


Configuring WS Federation 


The first two topics in this section describe two different methods for setting up federation with a 
SharePoint server. The next sections describe how you can manage and modify WS Federation 
providers and configure Security Token Service (STS). STS is used to process authentication 
requests received at Identity Server for the WS Federation protocol. 


The WS-Federation metadata can be obtained by using Samlv2Meta as described in the WS- 
Federation 1.1 and 1.2 specification. To obtain the metadata, use the following URL format: <base- 
url>/nidp/wsfed/metadata?type=Samlv2Meta. 

¢ Section 5.2.8.1, “Using Identity Server as an Identity Provider for ADFS,” on page 535 


¢ Section 5.2.8.2, “Using the ADFS Server as an Identity Provider for an Access Manager 
Protected Resource,” on page 545 


¢ Section 5.2.8.3, “Managing WS Federation Providers,” on page 551 

¢ Section 5.2.8.4, “Modifying a WS Federation Identity Provider,” on page 552 
¢ Section 5.2.8.5, “Modifying a WS Federation Service Provider,” on page 556 
¢ Section 5.2.8.6, “Configuring STS Attribute Sets,” on page 558 

¢ Section 5.2.8.7, “Configuring STS Authentication Methods,” on page 559 

¢ Section 5.2.8.8, “Configuring STS Authentication Request,” on page 559 


Using Identity Server as an Identity Provider for ADFS 
Identity Server can provide authentication for resources protected by an Active Directory Federation 
Services (ADFS) server. This allows Identity Server to provide single sign-on to Access Manager 


resources and ADFS resources, such as a SharePoint server. Figure 5-14 illustrates this 
configuration. 
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Figure 5-14 Accessing SharePoint Resources with an Identity Server 
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In this scenario, the following exchanges occur: 


1. The user requests access to a SharePoint server protected by the ADFS server. 
2. The resource sends an authentication request to the ADFS server. 


3. The ADFS server, which has been configured to use Identity Server as an identity provider, gives 
the user the option of logging in to Identity Server. 


4. The user logs in to Identity Server and is provided a token that is sent to the ADFS server and 
satisfies the request of the resource. 


5. The user is allowed to access the resource. 
The following section describe how to configure your servers for this scenario: 


+ “Configuring Identity Server” on page 536 

¢ “Configuring the ADFS Server” on page 541 
+ “Logging In” on page 544 

¢ “Troubleshooting” on page 544 
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+ “Prerequisites” on page 537 

¢ “Creating a New Authentication Contract” on page 537 

¢ “Setting the WS-Fed Contract to Be the Default Contract” on page 538 
¢ “Enabling the WS Federation Protocol” on page 538 

+ “Creating an Attribute Set for WS Federation” on page 538 

¢ “Enabling the Attribute Set” on page 539 

+ “Creating a WS Federation Service Provider” on page 539 

¢ “Configuring the Name Identifier Format” on page 540 
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¢ “Setting Up Roles for ClaimApp and TokenApp Claims” on page 540 
+ “Importing the ADFS Signing Certificate into the NIDP-Truststore” on page 541 


Prerequisites 


+ You have set up the Active Directory Federation Services, Active Directory, and SharePoint 
servers and the client as described in the ADFS guide from Microsoft. See the “Step-by-Step 
Guide for Active Directory Federation Services”. 


+ You have set up the Access Manager 4.0 system with a site configuration that is using SSL in 
Identity Server's base URL. See Chapter 17, “Enabling SSL Communication,” on page 977. 


Creating a New Authentication Contract 


The Microsoft ADFS server rejects the contract URI names of the default Access Manager contracts, 
which have a URI format of secure/name/password/uri. The ADFS server expects the URI to look 
like a URL. 


We suggest that you use the following format for the URI of all contracts that you want to use with the 
ADFS server: 


<baseurl>/name/password/uri 


If the DNS name of your Identity Server is idp-50.amlab.net, the URI would have the following 
format: 


https://idp-50.amlab.net :8443/nidp/name/password/uri 


This URL does not resolve to anything because Identity Server interprets it as a contract URI and not 
a URL. 


To create a new authentication contract: 


1 Click Devices > Identity Servers > Edit > Local > Contracts. 
2 Click New, then fill in the following fields: 
Display name: Specify a name, for example WS-Fed Contract. 


URI: Specify a URI, for example https://idp-50.amlab.net :8443/nidp/name/password/ 
uri. 


Satisfiable by External Provider: Enable this option. The ADFS server needs to satisfy this 
contract. 


3 Move Name/Password - Form to the Methods list. 
4 Click Next, then fill in the following fields: 


ID: Leave this field blank. You only need to supply a value when you want a reference that you 
can use externally. 


Text: Specify a description that is available to the user when the user mouses over the card. 


Image: Select an image, such as Form Auth Username Password. This is the default image for 
the Name/Password - Form contract. 


Show Card: Enable this option so that the card can be presented to the user as a login option. 
5 Click Finish. 
6 Continue with “Setting the WS-Fed Contract to Be the Default Contract” on page 538. 
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Setting the WS-Fed Contract to Be the Default Contract 


It is not possible to specify the contract to request from the ADFS service provider to Identity Server. 
You must either set the contract for WS-Fed to be the default, or have your users remember to click 
that contract every time. 

1 On the Local page of Identity Server, click Defaults. 

2 For the Authentication Contract option, select the WS-Fed Contract. 

3 Click Apply. 

4 Continue with “Enabling the WS Federation Protocol” on page 538. 


Enabling the WS Federation Protocol 


Access Manager ships with only SAML 1.1, Liberty, and SAML 2.0 enabled by default. To use the WS 
Federation protocol, you must enable it on Identity Server. 

1 Click the General tab. 

2 In the Enabled Protocols section, select WS Federation. 

3 Click OK. 

4 Update Identity Server. 

5 Continue with “Creating an Attribute Set for WS Federation” on page 538. 


Creating an Attribute Set for WS Federation 


The WS Federation namespace is http: //schemas.xmlsoap.org/claims. With WS Federation, 
you need to decide which attributes you want to share during authentication. This scenario uses the 
LDAP mail attribute and the All Roles attribute. 
1 On Identity Servers page, click Shared Settings. 
2 Tocreate a new attribute set, click New, then fill in the following fields: 
Set Name: Specify a name that identifies the purpose of the set, for example, wsfed_attributes. 
Select set to use as template: Select None. 
3 Click Next. 
4 To add a mapping for the mail attribute: 
4a Click New. 
4b Fill in the following fields: 
Local attribute: Select LDAP Attribute:mail [LDAP Attribute Profile]. 


Remote attribute: Specify emailAddress. This is the attribute that this scenario uses for 
user identification. 


Remote namespace: Select the radio button by the text box, then specify the following 
namespace: 


http://schemas.xmlsoap.org/claims 
4c Click OK. 
5 To add a mapping for the All Roles attribute: 
5a Click New. 
5b Fill in the following fields: 
Local attribute: Select All Roles. 
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Remote attribute: Specify group. This is the name of the attribute that is used to share 
roles. 


Remote namespace: Select the radio button by the text box, then specify the following 
namespace: 


http://schemas.xmlsoap.org/claims 


5c Click OK. 
6 Click Finish. 
7 Continue with “Enabling the Attribute Set” on page 539. 


Enabling the Attribute Set 


Because the WS Federation protocol uses STS, you must enable the attribute set for STS to use it in 
an WS Federation relationship. 

1 On Identity Servers page, click Servers > Edit > WS Federation > STS Attribute Sets. 

2 Move the WS Federation attribute set to the Attribute sets list. 


3 Select the WS Federation attribute set and use the up-arrow to make it first in the Attribute set 
list. 


4 Click OK, then update Identity Server. 
Creating a WS Federation Service Provider 


To establish a trusted relationship with the ADFS server, you need to set up the Trey Research site as 
a service provider. The trusted relationship allows the service provider to trust Identity Server for user 
authentication credentials. 


Trey Research is the default name for the ADFS resource server. If you have used another name, 
substitute it when following these instructions. To create a service provider, you need to know the 
following about the ADFS resource server. 


Table 5-3 ADFS Resource Server Information 


What You Need to Know Default Value and Description 


Provider ID Default Value: urn: federation: treyresearch 


This is the value that the ADFS server provides to Identity Server in the realm 
parameter of the query string. This value is specified in the Properties of the Trust 
Policy page on the ADFS server. The parameter label is Federation Service URI. 


Sign-on URL Default Value: https: //adfsresource.treyresearch.net/adfs/ls/ 


This is the value that the identity provider redirects the user to after login. Although 
it is listed as optional, and is optional between two Access Manager Identity 
Servers, the ADFS server does not send this value to the identity provider. It is 
required when setting up a trusted relationship between an ADFS server and a 
Access Manager Identity Server. 


This URL is listed in the Properties of the Trust Policy page on the ADFS server. 
The parameter label is Federation Services endpoint URL. 


Logout URL Default Value: https: //adfsresource.treyresearch.net/adfs/ls/ 


This parameter is optional. If it is specified, the user is logged out of the ADFS 
server and Identity Server. 
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What You Need to Know Default Value and Description 


Signing Certificate This is the certificate that the ADFS server uses for signing. 


You need to export it from the ADFS server. It can be retrieved from the properties 
of the Trust Policy on the ADFS Server on the Verification Certificates tab. This 
certificate is a self-signed certificate that you generated when following the Active 
Directory step-by-step guide. 


To create a service provider configuration: 


1 On Identity Servers page, click Edit > WS Federation. 
2 Click New > Service Provider, then fill in the following fields: 
Name: Specify a name that identifies the service provider, such as TreyResearch. 


Provider ID: Specify the provider ID of the ADFS server. The default value is 
urn: federation: treyresearch. 


Sign-on URL: Specify the URL that the user is redirected to after login. The default value is 
https://adfsresource.treyresearch.net/adfs/1s/. 


Logout URL: (Optional) Specify the URL that the user can use for logging out. The default value 
is https://adfsresource. treyresearch.net/adfs/1s. 


Service Provider: Specify the path to the signing certificate of the ADFS server. 
3 Click Next, confirm the certificate, then click Finish. 
4 Continue with “Configuring the Name Identifier Format” on page 540. 


Configuring the Name Identifier Format 


The Unspecified Name Identifier format is the default for a newly created WS Federation service 
provider, but this name identifier format does not work with the ADFS federation server. Additionally, 
some Group Claims (Adatum ClaimApp Claim and Adatum TokenApp Claim) must be satisfied to 
gain access to the SharePoint server. 

1 On the WS Federation page, click the name of the TreyResearch service provider. 

2 Click Attributes, then fill in the following fields: 
Attribute set: Select the WS Federation attribute set you created. 
Send with authentication: Move the All Roles attribute to the Send with authentication list. 
Click Apply, then click Authentication Response. 
Select E-mail for the Name Identifier Format. 
Select LDAP Attribute:mail [LDAP Attribute Profile] as the value for the e-mail identifier. 
Click OK twice, then update Identity Server. 
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Continue with “Setting Up Roles for ClaimApp and TokenApp Claims” on page 540. 


Setting Up Roles for ClaimApp and TokenApp Claims 


When users access resources on the ADFS server, they need to have two roles assigned: a 
ClaimApp role and a TokenApp role. The following steps explain how to create these two roles so that 
they are assigned to all users that log in to Identity Server. 

1 On Identity Servers page, click Edit > Roles > Manage Policies. 

2 Click New, specify a name for the policy, select Identity Server: Roles, then click OK. 

3 On the Rule 1 page, leave Condition Group 1 blank. 
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With no conditions to match, this rule matches all authenticated users. 

In the Actions section, click New > Activate Role. 

In the text box, specify ClaimApp. 

In the Actions section, click New > Activate Role. 

In the text box, specify TokenApp. 

Click OK twice, then click Apply Changes. 

Click Close. 

10 On the Roles page, select the role policy you just created, then click Enable. 

11 Click OK, then update Identity Server. 

12 Continue with “Importing the ADFS Signing Certificate into the NIDP-Truststore” on page 541. 
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Importing the ADFS Signing Certificate into the NIDP-Truststore 


The Access Manager Identity Provider (NIDP) must have the trusted root of the ADFS signing 
certificate (or the certificate itself) listed in its Trust Store, as well as specified in the relationship. This 
is because most ADFS signing certificates are part of a certificate chain, and the certificate that goes 
into the metadata is not the same as the trusted root of that certificate. However, because the Active 
Directory step-by-step guide uses self-signed certificates for signing, it is the same certificate in both 
the Trust Store and in the relationship. 


To import the ADFS signing certificate’s trusted root (or the certificate itself) into the NIDP-Truststore: 


1 On Identity Servers page, click Edit > Security > NIDP Trust Store. 

2 Click Add. 

3 Next to the Trusted Root(s) field, click the Select Trusted Root(s) icon. 
This adds the trusted root of the ADFS signing certificate to the Trust Store. 


4 On the Select Trusted Roots page, select the trusted root or certificate that you want to import, 
then click Add Trusted Roots to Trust Stores. 


If there is no trusted root or certificate in the list, click Import. This enables you to import a 
trusted root or certificate. 


5 Next to the Trust store(s) field, click the Select Keystore icon. 
6 Select the trust stores where you want to add the trusted root or certificate, then click OK twice. 
7 Update Identity Server so that the changes can take effect. 


This finishes the configuration that must be done on Identity Server for Identity Server to trust the 
ADFS server. The ADFS server must be configured to trust Identity Server. Continue with 
“Configuring the ADFS Server” on page 541. 


Configuring the ADFS Server 


The following tasks must be completed on the Trey Research server (adfsresouce.treyresearch.net) 
to establish trust with the Access Manager Identity Server. 

+ “Enabling E-mail as a Claim Type” on page 542 

¢ “Creating an Account Partners Configuration” on page 542 

¢ “Enabling ClaimApp and TokenApp Claims” on page 543 

¢ “Disabling CRL Checking” on page 543 
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Enabling E-mail as a Claim Type 


There are three types of claims for identity that can be enabled on an ADFS server. They are 
Common Name, E-mail, and User Principal Name. The ADFS step-by-step guide specifies that you 
do everything with a User Principal Name, which is an Active Directory convention. Although it could 
be given an e-mail name that looks the same, it is not. This scenario selects to use E-mail instead of 
Common Name because E-mail is a more common configuration. 

1 From the Administrative Tools, open the Active Directory Federation Services tool. 


2 Navigate to the Organizational Claims by clicking Federation Service > Trust Policy > My 
Organization. 


3 Verify that E-mail is in this list. If it isn’t, move it to the list. 


4 Navigate to your Token-based Application and enable e-mail by right-clicking the application, 
editing the properties, and clicking the Enabled box. 


5 Navigate to your Claims-aware Application and repeat the process. 
6 Continue with “Creating an Account Partners Configuration” on page 542. 


Creating an Account Partners Configuration 


WS Federation requires a two-way trust relationship. Both the identity provider and the service 
provider must be configured to trust the other provider. This task sets up the trust between the ADFS 
server and Identity Server. 


1 In the Active Directory Federation Services console, navigate to the Account Partners by clicking 
Federation Services >Trust Policy > Partner Organizations. 
2 Right-click Partner Organizations, then select New > Account Partner. 
3 Supply the following information in the wizard: 
+ You do not have an account partner policy file. 
+ For the display name, specify the DNS name of Identity Server. 
+ For the Federation Services URI, specify the following: 


https://<DNS_Name>:8443/nidp/wsfed/ 


Replace <DNS_Name> with the DNS name of Identity Server. 
This URI is the base URL of your Identity Server with the addition of /wsfed/ on the end. 
+ For the Federation Services endpoint URL, specify the following: 


https://<DNS_Name>:8443/nidp/wsfed/ep 


Replace <DNS_Name> with the DNS name of Identity Server. 
This URL is the base URL of your Identify Server with the addition of /wsfed/ep at the end. 


¢ For the verification certificate, import the trusted root of the signing certificate on your 
Identity Server. 


If you have not changed it, you need the Organizational CA certificate from your 
Administration Console. This is the trusted root for the test-signing certificate. 


+ Select Federated Web SSO. 
Identity Server is outside of any forest, so do not select Forest Trust. 
+ Select the E-mail claim. 
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+ Add the suffix that you will be using for your e-mail address. 


You need to have the e-mail end in a suffix that the ADFS server is expecting, such as 
@novell.com, which grants access to any user with that e-mail suffix. 


4 Enable this account partner. 
5 Finish the wizard. 
6 Continue with “Enabling ClaimApp and TokenApp Claims” on page 543. 


Enabling ClaimApp and TokenApp Claims 


The Active Directory step-by-step guide sets up these roles to be used by the resources. You set 
them up to be sent in the All Roles attribute from Identity Server. You must map these roles into the 
Adatum ClaimApp Claim and the Adatum TokenApp Claim. 


1 In the Active Directory Federation Services console, click the account partner that you created 
for Identity Server (see “Creating an Account Partners Configuration” on page 542). 


2 Right click the account partner, then create a new Incoming Group Claim Mapping with the 
following values: 


Incoming group claim name: Specify ClaimApp. 
Organization group claim: Specify Adatum ClaimApp Claim. 


3 Right-click the account partner, and create another Incoming Group Claim Mapping with the 
following values: 


Incoming group claim name: Specify TokenApp. 
Organization group claim: Specify Adatum TokenApp Claim. 
4 Continue with “Disabling CRL Checking” on page 543. 


Disabling CRL Checking 


If you are using the Access Manager certificate authority as your trusted root for the signing certificate 
(test-signing certificate), there is no CRL information in that certificate. However, the ADFS has a 
mandatory requirement to do CRL checking on any certificate that they receive. For instructions on 
how to disable this checking, see “Turn CRL checking on or off’. 


Use the following tips as you follow these instructions. 


+ Create a file from the script contained at that link called TpCr1ichk.vbs. 
¢ Exit the Active Directory Federation Services console. 


If you do not exit the console, the console overwrites the changes made by the script file and 
CRL checking is not turned off. 


+ Run the command with the following syntax: 
Cscript TpCrichk.vbs <location of ADFS>\TrustPolicy.xml "<service URI>" None 


Replace </ocation of ADFS> with the location of the ADFS TrustPolicy. xml file. The default 
location is C: \ADFS\TrustPolicy. xml. 


Replace <service URI> with the URI you specified in Step 3 on page 542. If the DNS name of 
your Identity Server is idp-50.amlab.net, replace it with https://idp-50.amlab.ne:8443/ 
nidp/wsfed/. 


Your command must look similar to the following: 


Cscript TpCrichk.vbs C:\ADFS\TrustPolicy.xml "https://idp-50.amlab.net:8443/ 
nidp/wsfed/" None 


Configuring Authentication 543 


544 


Logging In 
1 Ina browser on your client machine, enter the URL of the SharePoint server. For example: 
https://adfsweb.treyresearch.net/default.aspx 


2 Select the IDP from the drop-down list of home realm, then submit the request. 
If you are not prompted for the realm, clear all cookies in the browser and try again. 
3 Log in with a user at the Access Manager Identity Provider 


4 Verify that you can access the SharePoint server.If you only see a page that says Server Error 
in '/adfs' Application, see “Turning On Logging on the ADFS Server” on page 544 and 
follow the instructions in “Common Errors” on page 544. 


Troubleshooting 
¢ “Turning On Logging on the ADFS Server” on page 544 
+ “Common Errors” on page 544 


Turning On Logging on the ADFS Server 


If you see the message Server Error in '/adfs' Application displayed in the client's browser, 
the best place to look for the cause is in the ADFS log file. 


To turn on this log file: 


1 In the Active Directory Federation Services console, right-click Federation Service, then click 
Properties. 


2 Click the Troubleshooting tab, then enable everything on the page. 
3 Click OK, then look for the file that is created in the path listed in the Log files directory. 
4 Look in that file for reasons that the federation is failing. 

For an explanation of some of the common errors, see “Common Errors” on page 544. 


Common Errors 


+ “[ERROR] SamlViolatesSaml:” on page 544 

+ “[ERROR] Saml contains an unknown NameldentifierFormat:” on page 544 
+ “CRL Errors” on page 545 

+ “[ERROR] EmailClaim.set_Email:” on page 545 


[ERROR] SamlViolatesSaml: 


Error parsing AuthenticationMethod: Invalid URI: The format of the URI could not be determined. 


Cause: This is because the contract has the wrong format for its URI. The URI must start with urn: or 
http://. Change the contract and try again. 


[ERROR] Saml contains an unknown NameldentifierFormat: 


Issuer=https://idp-51.amlab.net:8443/nidp/wsfed/; Format=urn:oasis:names:tc:SAML:1.1:nameid- 
format:unspecified 


Cause: The name identifier format is set to unspecified, and it needs to be set to E-mail. 
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[ERROR] Samli contains an unknown Claim name/namespace: 


Issuer=https://idp-51.amlab.net:8443/nidp/wsfed/; 
Namespace=urn:oasis:names:tc:SAML:1.0:assertion; Name=emailaddress 


Cause: The emailAddress attribute is not in the correct namespace for WSFed. 


CRL Errors 


+ 2008-08-01T19:56:55 [WARNING] VerifyCertChain: Cert chain did not verify - error code was 
0x80092012 


+ 2008-08-01T19:56:55 [ERROR] Keylnfo processing failed because the trusted certificate does 
not have a a valid certificate chain. Thumbprint = 
09667EB26101A98F44034A3EBAAF9A3A09A0F327 


+ 2008-08-01T19:56:55 [WARNING] Failing signature verification because the Keylnfo section 
failed to produce a key. 


+ 2008-08-01T19:56:55 [WARNING] SAML token signature was not valid: AssertionID = 
idZOKQHOkfj VK8kmKfv6YaVPgIRNo 


Cause: The CRL check isn't turned off. See “Disabling CRL Checking” on page 543. 


[ERROR] EmailClaim.set_Email: 
Email 'mPmNXOA8Rv+j16L1iINKn/4HVpfeJ3av1L9cOGQ==' has invalid format 


Cause: The drop-down list next to E-mail in the identifier format was not changed from <Not 
Specified> to a value with a valid e-mail address in it. 


Using the ADFS Server as an Identity Provider for an Access 
Manager Protected Resource 


The Active Directory Federation Services server can be configured to provide authentication for a 
resource protected by Access Manager. 


Figure 5-15 Using an ADFS Server for Access Manager Authentication 
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In this scenario, the following exchanges occur: 


1. The user requests access to a resource protected by an Access Gateway. 
2. The resource sends an authentication request to the Access Manager Identity Server. 


3. Identity Server is configured to trust an Active Directory Federation Services server and gives 
the user the option of logging in at the Active Directory Federation Services server. 


4. The user logs into the Active Directory Federation Services server and is provided a token 
5. The token is sent to Identity Server. 
6. The token satisfies the authentication requirements of the resource, so the user is allowed to 
access the resource. 
The following sections describe how to configure this scenario. 


¢ “Configuring Identity Server as a Service Provider” on page 546 

¢ “Configuring the ADFS Server to Be an Identity Provider” on page 549 
¢ “Logging In” on page 550 

¢ “Additional WS Federation Configuration Options” on page 550 


Configuring Identity Server as a Service Provider 


+ “Prerequisites” on page 546 

+ “Enabling the WS Federation Protocol” on page 546 

¢ “Creating a WS Federation Identity Provider” on page 547 

¢ “Modifying the User Identification Specification” on page 548 

+ “Importing the ADFS Signing Certificate into the NIDP-Truststore” on page 548 


Prerequisites 


+ You have set up the Active Directory Federation Services, Active Directory, and SharePoint 
servers and the client as described in the ADFS guide from Microsoft. See the “Step-by-Step 
Guide for Active Directory Federation Services”. 


+ You have set up the Access Manager system with a site configuration that is using SSL in 
Identity Server's base URL. See Chapter 17, “Enabling SSL Communication,” on page 977. 


+ Enable the Liberty Personal Profile. 
Click Identity Servers > Edit > Liberty > Web Service Provider. Select the Personal Profile, then 
click Enable > Apply. Update Identity Server. 
Enabling the WS Federation Protocol 


Access Manager ships with only SAML 1.1, Liberty, and SAML 2.0 enabled by default. To use the WS 
Federation protocol, it must be enabled on Identity Server. 


1 Click Devices > Identity Servers > Edit. 

2 In the Enabled Protocols section of the General Configuration page, select WS Federation. 
3 Click OK. 

4 Update Identity Server. 

5 Continue with “Creating a WS Federation Identity Provider” on page 547. 
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Creating a WS Federation Identity Provider 


To have a trust relationship, you need to set up the Adatum site (adfsaccount.adatum.com) as an 
identity provider for Identity Server. 


Adatum is the default name for the identity provider. If you have used another name, substitute it 
when following these instructions. To create an identity provider, you need to know the following 
information about the Adatum site: 


Table 5-4 Adatum Values 


What You Need to Default Value and Description 
Know 
Provider ID Default Value: urn: federation: adatum 


The ADFS server provides this value to the service provider in the realm parameter 
in the assertion. You set this value in the Properties of the Trust Policy on the ADFS 
server. The label is Federation Service URI. 


Sign-on URL Default Value: https: //adfsaccount.adatum.com/adfs/1s/ 


The service provider uses this value to redirect the user for login. This URL is listed 
in the Properties of the Trust Policy on the ADFS server. The label is Federation 
Services endpoint URL. 


Logout URL Default Value: https: //adfsresource.treyresearch.net/adfs/ls/ 


The ADFS server makes no distinction between the login and logout URL. Access 
Manager has separate URLs for login and logout, but from a Access Manager 
Identity Server to an ADFS server, they are the same. 


Signing Certificate This is the certificate that the ADFS server uses for signing. 


You need to export it from the ADFS server. It can be retrieved from the properties of 
the Trust Policy on the ADFS Server on the Verification Certificates tab. This 
certificate is a self-signed certificate that you generated when following the step-by- 
step guide. 


To create an identity provider: 


1 Click Devices > Identity Servers > Edit > WS Federation. 
2 On the WS Federation page, click New, select Identity Provider, then fill in the following fields: 
Name: Specify a name that identifies the identity provider, such as Adatum. 


Provider ID: Specify the federation service URI of the identity provider, for example 
urn: federation: adatum. 


Sign-on URL: Specify the URL for logging in, such as https: //adfsaccount.adatum.com/ 
adfs/1s/. 


Logout URL: Specify the URL for logging out, such as https: // 
adfsresource.treyresearch.net/adfs/ls/ 


Identity Provider: Specify the path to the signing certificate of the ADFS server. 
3 Confirm the certificate, then click Next. 
4 For the authentication card, specify the following values: 
ID: Leave this field blank. 
Text: Specify a description that is available to the user when the user mouses over the card. 
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Image: Select an image, such as Customizable, or any other image. 

Show Card: Enable this option so that the card can be presented to the user as a login option. 
5 Click Finish. 
6 Continue with “Modifying the User Identification Specification” on page 548. 


Modifying the User Identification Specification 


The default settings for user identification are set to do nothing. The user can authenticated but the 
user is not identified as a local user on the system. This is not the scenario we are configuring. We 
want the user to be identified on the local system. Additionally, we want to specify which contract on 
Access Gateway is satisfied with this identification. If a contract is not specified, Access Gateway 
resources must be configured to use the Any Contract option, which is not a typical configuration. 
On the WS Federation page, click the name of the Adatum identity provider configuration. 
Click User Identification. 

For Satisfies contract, select Name/Password — Form. 

Select Allow federation. 

For the User Identification Method, select Authenticate. 

Click OK twice. 

Update the Identity Provider. 
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Continue with “Importing the ADFS Signing Certificate into the NIDP-Truststore” on page 548. 


Importing the ADFS Signing Certificate into the NIDP-Truststore 


Identity Server must have the trusted root of the ADFS signing certificate (or the certificate itself) 
listed in its trust store, as well as specified in the relationship. This is because most ADFS signing 
certificates have a chain, and the certificate that goes into the metadata is not the same as the trusted 
root of that certificate. However, because the Active Directory step-by-step guide uses self-signed 
certificates for signing, it is the same certificate in both the trust store and in the relationship. 


To import the ADFS signing certificate’s trusted root (or the certificate itself) into the NIDP-Truststore: 


1 On Identity Servers page, click Edit > Security > NIDP Trust Store. 

2 Click Add. 

3 Next to the Trusted Root(s) field, click the Select Trusted Root(s) icon. 
This adds the trusted root of the ADFS signing certificate to the Trust Store. 


4 On the Select Trusted Roots page, select the trusted root or certificate that you want to import, 
then click Add Trusted Roots to Trust Stores. 


If there is no trusted root or certificate in the list, click Import. This enables you to import a 
trusted root or certificate. 


5 Next to the Trust store(s) field, click the Select Keystore icon. 
6 Select the trust stores where you want to add the trusted root or certificate, then click OK twice. 
7 Update Identity Server so that changes can take effect. 
This ends the basic configuration that must be done to for Identity Server to trust the ADFS server as 
an identity provider. However, the ADFS server needs to be configured to act as an identity server 


and to trust Identity Server. Continue with “Configuring the ADFS Server to Be an Identity Provider” 
on page 549. 
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Configuring the ADFS Server to Be an Identity Provider 


The following tasks describe the minimum configuration required for the ADFS server to act as an 
identity provider for the Access Manager Identity Server. 

¢ “Enabling a Claim Type for a Resource Partner” on page 549 

¢ “Creating a Resource Partner” on page 549 


For additional configuration options, see “Additional WS Federation Configuration Options” on 
page 550. 


Enabling a Claim Type for a Resource Partner 


You can enable three types of claims for identity on an ADFS Federation server. They are Common 
Name, E-mail, and User Principal Name. The ADFS step-by-step guide specifies that you do 
everything with a User Principal Name, which is an Active Directory convention. Although it could be 
given an e-mail that looks the same, it is not. This scenario selects to use E-mail instead of Common 
Name because E-mail is a more common configuration. 

1 In the Administrative Tools, open the Active Directory Federation Services tool. 


2 Navigate to the Organizational Claims by clicking Federation Service > Trust Policy > My 
Organization. 


3 Ensure that E-mail is in this list. 
4 Navigate to Active Directory by clicking Federation Services > Trust Policy > Account Stores. 
5 Enable the E-mail Organizational Claim: 
5a Right-click this claim, then select Properties. 
5b Click the Enabled box. 
5c Add the LDAP mail attribute by clicking Settings > LDAP attribute and selecting mail. 
This is the LDAP attribute in Active Directory where the user’s e-mail address is stored. 
5d Click OK. 


6 Verify that the user you are going to use for authentication has an E-mail address in the mail 
attribute. 


7 Continue with “Creating a Resource Partner” on page 549. 


Creating a Resource Partner 


The WS Federation protocol requires a two-way trust. The identity provider must be configured to 
trust the service provider, and the service provider must be configured to trust the identity provider. 
You have already set up the service provider to trust the identity provider (see “Creating a WS 
Federation Identity Provider” on page 547). This section sets up the trust so that the identity provider 
(the ADFS server) trusts the service provider (Identity Server). 


1 Inthe Active Directory Federation Services console, access the Resource Partners page by 
clicking Federation Services > Trust Policy > Partner Organizations. 
2 Right-click the Partner Organizations, then click New > Resource Partner. 
3 Supply the following information in the wizard: 
+ You do not have a resource partner policy file to import. 
+ For the display name, specify the DNS name of Identity Server. 
+ For the Federation Services URI, enter the following: 


https: //<DNS_Name>:8443/nidp/wsfed/ 
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Replace <DNS_Name> with the name of your Identity Server. 
This is the base URL of your Identity Server with the addition of /wsfed/ at the end. 
+ For the Federation Services endpoint URL, specify the following: 


https://<DNS_Name>:8443/nidp/wsfed/spassertion_consumer 


Replace <DNS_Name> with the name of your Identity Server. 


This is the base URL of your Identity Server with the addition of /wsfed/ 
spassertion_consumer at the end. 


+ Select Federated Web SSO. 
Identity Server is outside of any forest, so do not select Forest Trust. 
+ Select the E-mail claim. 
+ Select the Pass all E-mail suffixes through unchanged option. 
4 Enable this resource partner. 
5 Finish the wizard. 
6 To test the configuration, continue with “Logging In” on page 550. 


Logging In 


1 In a client browser, enter the base URL of your Identity Server. 
2 From the list of cards, select the Adatum contract. 


3 (Conditional) If you are not joined to the Adatum domain, enter a username and password in the 
browser pop-up. Use a name and a password that are valid in the Adatum domain. 


If you are using the client that is joined to the Adatum domain, the card uses a Kerberos ticket to 
authenticate to the ADFS identity provider (resource partner). 


4 When you are directed back to Identity Server for Federation User Identification, log in to Identity 
Server with a username and password that is valid for Identity Server (the service provider). 


5 Verify that you are authenticated. 
6 Close the browser. 
7 Log in again. 
This time you are granted access without entering credentials at the service provider. 


Additional WS Federation Configuration Options 


You can enable the sharing of attribute information from Identity Server to the ADFS server. This 
involves creating an attribute set and enabling the sending of the attributes at authentication. See 
“Configuring the Attributes Obtained at Authentication” on page 553. 


For other options that can be modified after you have created the trusted identity server configuration, 
see “Modifying a WS Federation Identity Provider” on page 552. 
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Managing WS Federation Providers 


The WS Federation page allows you to create or edit trusted identity providers and trusted service 
providers. When you create an identity provider configuration, you are configuring Identity Server to 
be a WS Federation resource partner. When you create a service provider configuration, you are 
configuring Identity Server to be a WS Federation account partner. 

1 Click Devices > Identity Servers > Edit > WS Federation. 

2 Select one of the following actions: 


New: Launches the Create Trusted Identity Provider Wizard or the Create Trusted Service 
Provider Wizard, depending on your selection. For more information, see one of the following: 


¢ “Creating an Identity Provider for WS Federation” on page 551 
¢ “Creating a Service Provider for WS Federation” on page 552 


Delete: Allows you to delete the selected identity or service provider. This action deletes the 
definition. 


Enable: Enables the selected identity or service provider. 


Disable: Disables the selected identity or service provider. When the provider is disabled, the 
server does not load the definition. However, the definition is not deleted. 


Modify: Click the name of a provider. For configuration information, see “Modifying a WS 
Federation Identity Provider” on page 552 or “Modifying a WS Federation Service Provider” on 
page 556. 


3 Click OK, then update Identity Server. 


Creating an Identity Provider for WS Federation 


To have a trust relationship, you need to set up the ADFS server as an identity provider for Identity 
Server. 
1 Click Devices > Identity Servers > Edit > WS Federation. 
2 On the WS Federation page, click New, select Identity Provider, then fill in the following fields: 
Name: Specify a name that identifies the identity provider, such as Adatum. 


Provider ID: Specify the federation service URI of the identity provider, for example 
urn: federation: adatum. 


Sign-on URL: Specify the URL for logging in, such as https: //adfsaccount.adatum.com/ 
adfs/ls/. 


Logout URL: Specify the URL for logging out, such as https: // 
adfsresource.treyresearch.net/adfs/ls/ 


Identity Provider: Specify the path to the signing certificate of the ADFS server. 
3 Confirm the certificate, then click Next. 
4 For the authentication card, specify the following values: 
ID: Leave this field blank. 
Text: Specify a description that is available to the user when the user mouses over the card. 
Image: Select an image, such as Customizable, or any other image. 
Show Card: Enable this option so that the card can be presented to the user as a login option. 
5 Click Finish. 


For information about additional configuration steps required to use this identity provider, see “Using 
the ADFS Server as an Identity Provider for an Access Manager Protected Resource” on page 545. 
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Creating a Service Provider for WS Federation 


To establish a trusted relationship with the ADFS server, you need to set up the ADFS server as 
service provider. The trusted relationship allows the service provider to trust Identity Server for user 
authentication credentials. 
1 Click Devices > Identity Servers > Edit > WS Federation. 
2 Click New > Service Provider, then fill in the following fields: 
Name: Specify a name that identifies the service provider, such as TreyResearch. 


Provider ID: Specify the provider ID of the ADFS server. The default value is 
urn: federation: treyresearch. 


Sign-on URL: Specify the URL that the user is redirected to after login. The default value is 
https://adfsresource.treyresearch.net/adfs/1s/. 


Logout URL: (Optional) Specify the URL that the user can use for logging out. The default value 
is https: //adfsresource. treyresearch.net/adfs/1s. 


Service Provider: Specify the path to the signing certificate of the ADFS server. 
3 Click Next, confirm the certificate, then click Finish. 


For information about additional configuration steps required to use this service provider, see “Using 
Identity Server as an Identity Provider for ADFS” on page 535. 


Modifying a WS Federation Identity Provider 


This section explains how to modify a WS Federation identity provider after it has been created. 
“Creating an Identity Provider for WS Federation” on page 551 explains the steps required to create 
an identity provider. You can modify the following configuration details: 

+ “Renaming the Trusted Provider” on page 552 

¢ “Configuring the Attributes Obtained at Authentication” on page 553 

¢ “Modifying the User Identification Method” on page 553 

e “Viewing the WS Identity Provider Metadata” on page 554 

¢ “Editing the WS Identity Provider Metadata” on page 555 

¢ “Modifying the Authentication Card” on page 555 

e “Assertion Validity Window” on page 555 


Renaming the Trusted Provider 


1 Click Devices > Identity Servers > Edit > WS Federation > [Provider Name]. 
2 Inthe Name field, specify a new name for the trusted provider. 
3 Click OK twice, then update Identity Server. 
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Configuring the Attributes Obtained at Authentication 


When Identity Server creates its request to send to the identity provider, it uses the attributes that you 
have selected. The request asks the identity provider to provide values for these attributes. You can 
then use these attributes to create policies, to match user accounts, or if you allow provisioning, to 
create a user account on the service provider. 


To select the attributes: 


1 Click Devices > Identity Servers > Edit > WS Federation > [Identity Provider] > Attributes. 


2 (Conditional) To create an attribute set, select New Attribute Set from the Attribute Set drop- 
down menu. 


An attribute set is a group of attributes that can be exchanged with the trusted provider. For 
example, you can specify that the local attribute of any attribute in the Liberty profile (such as 
Informal Name) matches the remote attribute specified at the service provider. 


2a Specify a set name, then click Next. 
2b On the Define Attributes page, click New. 
2c Select a local attribute. 
2d Specify the name of the remote attribute. 
2e For the namespace, specify http://schemas.xmlsoap.org/claims. 
2f Click OK. 
2g To add other attributes to the set, repeat Step 2b through Step 2e. 
2h Click Finish. 
3 Select an attribute set. 
4 Select attributes from the Available list, and move them to the left side of the page. 
5 (Conditional) If you created a new attribute set, it must be enabled for STS. 
For more information, see “Enabling the Attribute Set” on page 539. 
6 Click OK, then update Identity Server. 


Modifying the User Identification Method 
The user identification method specifies how to identify the user. 


1 Click Devices > Identity Servers > Edit > WS Federation > [Identity Provider] > User 
Identification. 


2 Select the contract that can be used for authentication. Fill in the following field: 


Satisfies contract: Specifies the contract that is satisfied by the assertion received from the 
identity provider. WS Federation expects the URI name of the contract to look like a URL, so it 
rejects all default Access Manager contracts. You must create a contract with a URI that 
conforms to WS Federation requirements. 


For more information about how to create this contract, see “Creating a New Authentication 
Contract” on page 537. 


3 Specify whether the user can associate (federate) an account at the identity provider (the ADFS 
server) with an account at Identity Server. Fill in the following field: 


Allow federation: Indicates whether account federation is allowed. Enabling this option 
assumes that a user account exists at the provider or that a method is provided to create an 
account that can be associated with the user on subsequent logins. If you do not use this 
feature, authentication is permitted but is not associated with a particular user account. 
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4 Select one of the following methods for user identification: 


¢ Do nothing: Allows the user to authenticate without creating an association with a user 
account. This option cannot be used when federation is enabled. 


+ Authenticate: Allows the user to authenticate using a local account. 


¢ Allow ‘Provisioning’: Provides a button that the user can click to create an account 
when the authentication credentials do not match an existing account. 


¢ Provision account: Allows a new account to be created for the user when the 
authenticating credentials do not match an existing user. When federation is enabled, the 
new account is associated with the user and used with subsequent logins. When federation 
is not enabled, a new account is created every time the user logs in. 


This option requires that you specify a user provisioning method. 


¢ Attribute matching: Enables account matching. The service provider can uniquely identify 
a user in its directory by obtaining specific user attributes sent by the trusted identity 
provider. This option requires that you specify a user matching method. 


+ Prompt for password on successful match: Specifies whether to prompt the user 
for a password when the user’s name is matched to an account, to ensure that the 
account matches. 


5 (Conditional) If you selected a method that requires provisioning (Allow ‘Provisioning’ or 
Provision account), click the Provision settings icon and create a provisioning method. 


For configuration information, see “Defining the User Provisioning Method” on page 468. 


6 (Conditional) If you selected Attribute matching as the identification method, click the Attribute 
Matching settings icon and create a matching method. 


For configuration information, see “Configuring the Attribute Matching Method for Liberty or 
SAML 2.0” on page 466. 


7 Click OK twice, then update Identity Server. 


Viewing the WS Identity Provider Metadata 


You can view the metadata of the ADFS server, edit it, and view information about the signing 
certificate. 
1 Click Devices > Identity Servers > Edit > WS Federation > [Identity Provider] > Metadata. 
The following values need to be configured accurately: 


ID: This is provider ID. The ADFS server provides this value to the service provider in the realm 
parameter in the assertion. You set this value in the Properties of the Trust Policy on the ADFS 
server. The label is Federation Service URI. The default value is urn: federation: adatum. 


sloUrl: This is the sign-on URL. This URL is listed in the Properties of the Trust Policy on the 
ADFS server. The label is Federation Services endpoint URL. 


ssoUrl: This is the logout URL. The default value is https: // 
adfsresource.treyresearch.net/adfs/ls/. The ADFS server makes no distinction between 
the login URL and the logout URL. 


If the values do not match the ADFS values, you need to edit the metadata. 


2 To edit the metadata, click Edit. For configuration information, see “Editing the WS Identity 
Provider Metadata” on page 555. 


3 To view information about the signing certificate, click Certificates. 
4 Click OK twice. 
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Editing the WS Identity Provider Metadata 
You can view and edit the metadata of the ADFS server. 


1 Click Devices > Identity Servers > Edit > WS Federation > [Identity Provider] > Metadata > Edit. 
2 Configure the following fields: 


Provider ID: This is the provider ID. The ADFS server provides this value to the service provider 
in the realm parameter in the assertion. You set this value in the Properties of the Trust Policy 
on the ADFS server. The label is Federation Service URI. The default value is 

urn: federation: adatum. 


Sign-on URL: This is the sloUrl. This URL is listed in the Properties of the Trust Policy on the 
ADFS server. The label is Federation Services endpoint URL. 


Logout URL: This is the ssoUrl. The default value is https: // 
adfsresource.treyresearch.net/adfs/ls/. The ADFS server makes no distinction between 
the login URL and the logout URL. 


3 If you need to import a new signing certificate, click the Browse button and follow the prompts. 
4 To view information about the signing certificate, click Certificates. 
5 Click OK twice, then update Identity Server. 


Modifying the Authentication Card 


When you create an identity provider, you must also configure an authentication card. After it is 
created, you can modify it. 


1 Click Devices > Identity Servers > Edit > WS Federation > [Identity Provider] > Authentication 
Card. 


2 Modify the values in one or more of the following fields: 


ID: If you have need to reference this card outside of Administration Console, specify an 
alphanumeric value here. If you do not assign a value, Identity Server creates one for its internal 
use. The internal value is not persistent. Whenever Identity Server is rebooted, the value can 
change. A specified value is persistent. 


Text: Specify the text that is displayed on the card. This value, in combination with the image, 
indicates to the users the provider they are logging into. 


Image: Specify the image to be displayed on the card. Select the image from the drop-down list. 
To add an image to the list, click <Select local image>. 


Show Card: Determine whether the card is shown to the user, which allows the user to select 
and use the card for authentication. If this option is not selected, the card is only used when a 
service provider makes a request for the card. 


Passive Authentication Only: Select this option if you do not want Identity Server to prompt the 
user for credentials. If the user has already authenticated and the credentials satisfy the 
requirements of this contract, the user is passively authenticated. If the user’s credentials do not 
satisfy the requirements of this contract, the user is denied access. 


3 Click OK twice, then update Identity Server. 


Assertion Validity Window 


You can configure the assertion validity time for WS Federation Provider (SP) to accommodate clock 
skew between a service provider and a SAML identity provider. 


To set the assertion validity for WSFed configuration, go to Devices > Identity Servers > Edit > 
Options, click new and configure the following property: 
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Property Type: WSFED ASSERTION VALIDITY 

Property Value: Specify the assertion validity time in second 
Restart Tomcat by using the following command: 

Linux: /etc/init.d/novell-idp restart 

Windows: 

net stop Tomcat7 


net start Tomcat7 


Modifying a WS Federation Service Provider 


This section explains how to modify a WS Federation service provider after it has been created. 
“Creating a Service Provider for WS Federation” on page 552 explains the steps required to create 
the service provider. You can modify the following configuration details: 


e “Renaming the Service Provider” on page 556 

¢ “Configuring the Attributes Sent with Authentication” on page 556 
¢ “Modifying the Authentication Response” on page 557 

e “Viewing the WS Service Provider Metadata” on page 557 

¢ “Editing the WS Service Provider Metadata” on page 558 


Renaming the Service Provider 


1 Click Devices > Identity Servers > Edit > WS Federation > [Service Provider]. 
2 Inthe Name field, specify a new name for the service provider. 
3 Click OK twice, then update Identity Server. 


Configuring the Attributes Sent with Authentication 


When Identity Server creates its response for the service provider, it uses the attributes listed on the 
Attributes page. The response needs to contain the attributes that the service provider requires. If you 
do not own the service provider, you need to contact the administrator of the service provider and 
negotiate which attributes you need to send in the response. The service provider can then use these 
attributes to identify the user, to create policies, to match user accounts, or if it allows provisioning, to 
create a user account on the service provider. 


1 Click Devices > Identity Servers > Edit > WS Federation > [Service Provider] > Attributes. 


2 (Conditional) To create an attribute set, select New Attribute Set from the Attribute Set drop- 
down menu. 


An attribute set is a group of attributes that can be exchanged with the trusted provider. For 
example, you can specify that the local attribute of any attribute in the Liberty profile (such as 
Informal Name) matches the remote attribute specified at the service provider. 


2a Specify a set name, then click Next. 

2b On the Define Attributes page, click New. 

2c Select a local attribute. 

2d Specify the name of the remote attribute. 

2e For the namespace, specify http: //schemas.xmlsoap.org/claims. 
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2f Click OK. 
2g To add other attributes to the set, repeat Step 2b through Step 2e. 
2h Click Finish. 

3 Select an attribute set. 


4 Select attributes that you want to send from the Available list, and move them to the left side of 
the page. 


5 (Conditional) If you created a new attribute set, it must be enabled for STS. 
For more information, see “Enabling the Attribute Set” on page 539. 
6 Click OK, then update Identity Server. 


Modifying the Authentication Response 


When Identity Server sends its response to the service provider, the response can contain an 
identifier for the user. If you do not own the service provider, you need to contact the administrator of 
the service provider and negotiate whether the user needs to be identified and how to do the 
identification. If the service provider is going to use an attribute for user identification, that attribute 
needs to be in the attributes sent with authentication. See “Configuring the Attributes Sent with 
Authentication” on page 556. 


To select the user identification method to send in the response: 
1 Click Devices > Identity Servers > Edit > WS Federation > [Service Provider] > Authentication 
Response. 
2 For the format, select one of the following: 
Unspecified: Specifies that the SAML assertion contains an unspecified name identifier. 


E-mail: Specifies that the SAML assertion contains the user’s e-mail address for the name 
identifier. 


X509: Specifies that the SAML assertion contains an X.509 certificate for the name identifier. 


3 For the value, select an attribute that matches the format. For the Unspecified format, select the 
attribute that the service provider expects. 


The only values available are from the attribute set that you have created for WS Federation. 


4 To specify that this Identity Server must authenticate the user, disable the Use proxied requests 
option. When the option is disabled and Identity Server cannot authenticate the user, the user is 
denied access. 


When this option is enabled, Identity Server checks to see if other identity providers can satisfy 
the request. If one or more can, the user is allowed to select which identity provider performs the 
authentication. If a proxied identity provider performs the authentication, it sends the response to 
Identity Server. Identity Server then sends the response to the service provider. 


5 Click OK twice, then update Identity Server. 


Viewing the WS Service Provider Metadata 


You can view the metadata of the ADFS server, edit it, and view information about the signing 
certificate. 


1 Click Devices > Identity Servers > Edit > WS Federation > [Service Provider] > Metadata. 


The following values need to be configured accurately: 
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ID: This is provider ID. This is the value that the ADFS server provides to Identity Server in the 
realm parameter of the query string. This value is specified in the Properties of the Trust Policy 
page on the ADFS server. The parameter label is Federation Service URI. The default value is 
urn: federation: treyresearch. 


sloUrl: This is the sign-on URL. This URL is listed in the Properties of the Trust Policy on the 
ADFS server. The label is Federation Services endpoint URL. The default value is https: // 
adfsresource.treyresearch.net/adfs/1s/. 


ssoUrl: This is the logout URL. The default value is https: // 
adfsresource.treyresearch.net/adfs/ls/. The ADFS server makes no distinction between 
the login URL and the logout URL. 


If the values do not match the ADFS values, you need to edit the metadata. 


To edit the metadata, click Edit. For configuration information, see “Editing the WS Service 
Provider Metadata” on page 558. 


3 To view information about the signing certificate, click Certificates. 
4 Click OK twice. 

Editing the WS Service Provider Metadata 

You can view the metadata of the ADFS server and edit metadata. 


1 Click Devices > Identity Servers > Edit > WS Federation > [Service Provider] > Metadata > Edit. 


2 Configure the following fields: 


Provider ID: This is provider ID. This is the value that the ADFS server provides to Identity 
Server in the realm parameter of the query string. This value is specified in the Properties of the 
Trust Policy page on the ADFS server. The parameter label is Federation Service URI. The 
default value is urn: federation: treyresearch. 


Sign-on URL: This is the sloUrl. This URL is listed in the Properties of the Trust Policy on the 
ADFS server. The label is Federation Services endpoint URL. The default value is https: // 
adfsresource.treyresearch.net/adfs/1s/. 


Logout URL: This is the ssoUrl. The default value is https: // 
adfsresource.treyresearch.net/adfs/ls/. The ADFS server makes no distinction between 
the login URL and the logout URL. 


3 If you need to import a new signing certificate, click Browse and follow the prompts. 
4 To view information about the signing certificate, click Certificates. 
5 Click OK twice, then update Identity Server. 


Configuring STS Attribute Sets 


Use the Attribute Set page to select the attribute set or sets that contain attributes the STS can 
provide to a relying party. An attribute set must be created before you can select it. 


When creating an attribute set for the STS, you need to know which protocol you are going to use for 
the attribute set and select the attributes and namespace appropriate for the protocol. 


1 Click Devices > Identity Servers > Edit > WS Federation > STS Attribute Sets. 
2 To select a set, move the set from the Available attribute sets list to the Attribute sets list. 


WS Federation: There is no default attribute set for WS Federation. For information about how 
to create the set, see “Configuring the Attributes Obtained at Authentication” on page 553 and 
“Configuring the Attributes Sent with Authentication” on page 556. 


3 Click OK, then update Identity Server if you have changed the configuration. 
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5.2.8.8 


5.2.9 


Configuring STS Authentication Methods 


Use the Authentication Methods page to select the methods that can be used for authentication at the 
STS. The methods determine the credentials the user must supply for authentication and the user 
store that is used to verify the credentials. The WS Federation protocol does not use methods for 
authentication. 

1 Click Devices > Identity Servers > Edit > WS Federation > STS Authentication Methods. 

2 To enable a method, move the method from the Available methods list to the Methods list. 


All the methods that you have defined for Identity Server appear in the Available methods list, 
but the only default method that works is the Secure Name/Password-Form method. It has been 
extended so that it knows how to extract name and password information from a managed card 
that is not backed by a personal card. You can use the Secure Name/Password-Form class to 
create additional methods for specific user stores. 


You can also create a custom method, if required. For information, see NetIQ Access Manager 
Developer Tools and Examples (https://www.netiq.com/documentation/access-manager-43- 
developer-documentation/). 


3 Click OK, then update Identity Server if you have changed the configuration. 


Configuring STS Authentication Request 


Use the Authentication Request page to select the format for the name identifier that is returned in the 
SAML assertion. The selected attribute sets determine the values that are available for the formats. If 
you select a format but do not specify a value, a unique value is generated. 
1 Click Devices > Identity Servers > Edit > WS Federation > STS Authentication Request. 
2 Select one of the following: 
None: Indicates that the SAML assertion does not contain a name identifier. 


Unspecified: Specifies that the SAML assertion contains an unspecified name identifier. For the 
value, select the attribute that the relying party and the identity provider have agreed to use. 


E-mail: Specifies that the SAML assertion contains the user’s e-mail address for the name 
identifier. For the value, select an e-mail attribute. 


X509: Specifies that the SAML assertion contains an X.509 certificate for the name identifier. For 
the value, select an X.509 attribute. 


3 Click OK, then update Identity Server if you have changed the configuration. 


Configuring WS-Trust Security Token Service 


This section describes WS-Trust Security Token Service (WS-Trust STS) and how to configure it. 
Topics include: 

¢ Section 5.2.9.1, “Overview,” on page 560 

¢ Section 5.2.9.2, “Benefits,” on page 562 

¢ Section 5.2.9.3, “Scenarios,” on page 562 

¢ Section 5.2.9.4, “Configuring WS-Trust STS,” on page 568 

¢ Section 5.2.9.5, “Configuring Service Providers,” on page 570 

¢ Section 5.2.9.6, “Configuring Web Service Clients,” on page 575 

¢ Section 5.2.9.7, “Renew Token - Sample Request and Response,” on page 576 
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Overview 


Web services are software applications that interact over network by using the Hyper Text Transfer 
Protocol (HTTP). World Wide Web Consortium (W3C) describes Web services as a standard means 
of interoperating between software applications running on a variety of platforms and frameworks. A 
Web service provides a fine-grained service to its client. 


Web services use network for communication and data exchange spanning from protected network 
(intranet) to unprotected network (internet). This demands for security requirements such as client 
authentication, access control, data integrity, and confidentiality. 


You can secure Web services and protect your information against authentication attacks and 
unauthorized access by using security tokens. A security token contains a set of claims made by a 
client that includes details such as a user name, password, identity, key, and certificate. 


Access Manager addresses the need for a secure token mechanism through WS-Trust STS that is 
based on the WS-Trust protocol. WS-Trust is built on top of the WS-Security specification. It enables 
Web applications to construct trusted SOAP message exchanges. 


WS-Trust STS provides secure communication and integration between services. It issues and 
validates security tokens to establish trust relationships between a Web service client and a Web 
service provider. If the requestor (Web service client) does not have the necessary token to provide 
required claims to a service, it contacts WS-Trust STS and requests the needed tokens with proper 
claims. WS-Trust STS may in turn require its own set of claims for authenticating and authorizing the 
request for security tokens. 


How WS-Trust STS Works 


WS-Trust STS allows secure identity propagation and token exchange between Web services. It 
provides a standard framework for requesting and returning security tokens by using Request 
Security Token (RST) and Request Security Token Response (RSTR) messages. RST provides the 
means for requesting a security token from WS-Trust STS. RSTR contains the requested token, 
claims, and other related information. 


The Web service client provides its credentials to WS-Trust STS and gets a SAML token from WS- 
Trust STS. A trust is established between the Web service provider and WS-Trust STS. The Web 
service client presents the token from WS-Trust STS to the Web service provider. The Web service 
provider validates if the token has been issued from WS-Trust STS and grants access to the required 
service. 
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The following diagram illustrates an example of how WS-Trust STS facilitates a secure 


communication between a Web service client and a Web service provider through security tokens: 
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WS-Trust STS is designed to interoperate with many different Web Service environments and 
supports SOAP and WS-Trust specifications. 


Web services must implement the protocol defined in the WS-Trust 1.3 or 1.4 specification by making 


assertions based on evidence that it trusts, to whoever trusts it, or to specific recipients. For more 
information about WS-Trust specification, see WS-Trust 1.3 Specification and WS-Trust 1.4 
Specification. 


The following table lists supported SOAP and WS-Trust versions and corresponding namespaces: 


Specification Version Namespace 
Soap 1.1 http://schemas.xmlsoap.org/soap/envelope/ 
1.2 http://www.w3.org/2003/05/soap-envelope 
WS-Trust 1.3 http://docs.oasis-open.org/ws-sx/ws-trust/200512 
1.4 http://docs.oasis-open.org/ws-sx/ws-trust/200802 
NOTE 


+ WS-Trust STS supports SAML tokens in addition to usernametokens. 
WS-Trust STS can issue both SAML 1.1 and SAML 2.0 based tokens. 
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5.2.9.2 


5.2.9.3 


+ WS-Trust STS supports issuing, validating and renewing tokens. This release does not support 
canceling tokens. 


+ Web service clients and Web service providers must be in the same domain. This release does 
not support multiple domains. 


Benefits 


WS-Trust STS offers the following benefits: 


+ Enables the secure exchange of SOAP messages among Web services. 


¢ Facilitates identity delegation (through ActAs) and impersonation (through OnBehalfOf) where 
an authenticated user is granted access to downstream Web services. 


e Reduces complexity for the Web service consumer as the Web service consumer does not need 
token specific knowledge. 


Scenarios 


This section describes the basic scenarios supported by WS-Trust STS. 
¢ “Scenario 1: Web Service Client Communicating with Token Protected Web Service Provider” on 
page 562 
¢ “Scenario 2: Web Single Sign-On and STS” on page 563 
¢ “Scenario 3: Identity Delegation and Impersonation” on page 564 
¢ “Renewing a Token” on page 566 


e “Authentication by Using SAML Tokens” on page 567 


Scenario 1: Web Service Client Communicating with Token Protected Web 
Service Provider 


In this scenario, a Web service client situated outside the enterprise tries to access a Web service 
provider hosted inside the enterprise. 


This process consists of requesting a token by means of the request-response message pairs of a 
Request Security Token (RST) and a Request Security Token Response (RSTR). The tokens are 
included in SOAP messages. 
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The following diagram illustrates this scenario: 


Enterprise 


Username 
Token 


SAML 
Token WS-Trust STS 


Validate Sf Valid 


Web Service 
Client 
SAML 
Token 
4 a 


Web Service 
Provider 


1. AWeb service client, which is outside the enterprise, sends its credentials to WS-Trust STS and 
request for the security token through RST. 


2. WS-Trust STS verifies the client’s credentials and then issues a security token (SAML token) 
through RSTR. 


The Web service client caches the security token and then uses it in multiple requests to the 
Web service provider. 


3. The Web service client presents the token to the Web service provider. 
4. The Web service provider validates the token and sends the response to the Web service client. 


Scenario 2: Web Single Sign-On and STS 


In this scenario, a Web service client that resides as part of a Web application within an enterprise 
tries to access services from other Web service providers of the same enterprise. A user named Alice 
accesses to the Web application through a browser and needs single sign-on access to other 
applications. 
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1. AWeb application sends a single sign-on authentication request to WS-Trust STS on behalf of 
Alice. 
The Web application is residing within the enterprise. 


2. The Web application passes the credentials corresponding to the single sign-on session to the 
Web service client. 


3. The Web service client requests for security token by using the passed on credentials. 


4. WS-Trust STS verifies the credentials. After checking the credentials, it verifies if the Web 
service provider for which the token has been requested for is a trusted service provider. Then it 
issues a security token consumable by the service provider. 


5. The Web service client residing within the Web application presents the token to the Web service 
provider. The Web service client caches the security token and then uses it in multiple requests 
to the Web service provider. 


6. The Web service provider validates the token and sends the response to the Web service client 
residing within the Web application. 


The tokens are included in SOAP messages. 


Scenario 3: Identity Delegation and Impersonation 
In this scenario, a Web service provider requests services from other Web service providers. 
The following use-case explains this scenario: 


There are two Web service providers called Service1 and Service2 providing some fine-grained 
service. Both Service1 and Service2 require authentication and trust WS-Trust STS. A Web service 
client tries to access Service1 and requests for the service. To fulfill the request, Service1 needs to 
access the service of Service2. Service1 can request a token from WS-Trust STS to access Service2. 
This exchange of information happens through security tokens embedded in SOAP messages. 


This chaining of service request can be any number of nodes based on the implementation. 
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Requests for tokens can be made in two ways: 


¢ By using the ActAs element (Identity Delegation): The ActAs element is used for delegated 
requests. Delegated scenarios require composite delegation, where the final recipient of the 
issued token can see the entire delegation chain. ActAs is commonly used in multi-tiered 
systems to authenticate and pass information about identities between the tiers without having to 
pass this information at the application or business logic layer. 


¢ By using the OnBehalfOf element (Impersonation): The OnBehalfOf element is used for 
proxy requests. OnBehalfOf is used when the identity of only the original client is important. The 
final recipient of the issued token can only see claims about the original client. The information 
about intermediaries is not preserved. 


The following diagram illustrates the workflow: 
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The following workflow explains the ActAs scenario: 


1. The Web service client sends a RST to WS-Trust STS for its authentication. 


2. WS-Trust STS returns a SAML token to the client in the RSTR. Let us refer to this SAML token 
as token1. The subject of this SAML token is client. 


3. The client forwards the token1 with its SOAP request to Service. 


4. Then Service1 sends a RST to WS-Trust STS again authenticating itself to the STS. This time 
the RST contains the token1 inside the ActAs element. 


5. WS-Trust STS issues a SAML token (referred to as token2). The subject of this token is 
Servicet. It contains an attribute called ActAs with the value of client. 


6. Service1 sends token2 to Service2. By processing token2, Service2 understands that the 
original requester is client and Service1 is acting as the original requester. 


7. Service2 sends the response to Service’. 
8. Service’ forwards the response to the client. 
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The following workflow explains the OnBehalfOf scenario: 


1. The Web service client sends a RST to WS-Trust STS for its authentication. 


2. WS-Trust STS returns a SAML token to the client in the RSTR. Let us refer to this SAML token 
as token1. The subject of this SAML token is client. 


3. The client forwards the token1 with its SOAP request to Service. 


4. Then Service1 sends a RST to WS-Trust STS again authenticating itself to the STS. This time 
the RST contains the token1 inside the OnBehalfOf element. 


5. WS-Trust STS issues a SAML token (referred to as token2). The subject of this token is client. 


6. Service1 sends token2 to Service2. Service2 understands that the original requester is client 
but cannot see the details of Service. 


7. Service2 sends the response to Service. 
8. Service’ forwards the response to the client. 


IMPORTANT: Starting from Access Manager 4.0 SP1 release, the default binding supported is SOAP 
1.2. If you want to use SOAP 1.1 instead, perform the following steps on all instances of Identity 
Server: 


1. Traverse to the /opt/novell/nam/idp/webapps/nidp/WEB- INF folder and edit the sun- 
jaxws.xml file. 


2. Remove all instances of bindings from the endpoints in the sun-jaxws. xml file and save the 
changes. A binding is represented by the following line in this file: 


binding="http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/" 
3. Restart Identity Server using the /etc/init.d/novell-idp restart command. 


Renewing a Token 


The renew token operation helps in renewing a token issued by WS-Trust Security Token 
Service(STS). Only a token that is issued by an Identity Server that is part of the same cluster can be 
renewed. Tokens issued by a different Identity Server in a different cluster or by a third-party STS 
cannot be renewed. 


Each token generated by the STS is valid for the duration specified using the Token Lifetime setting. 
A token can be renewed only before lapse of the expiry period. For example: if the Token Lifetime has 
been specified as 180 seconds, token renew operation will succeed only till the 179th second. 


Workflow: 
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1. The Web service client sends a RST to WS-Trust STS for its authentication and WS-Trust STS 


returns a SAML token to the client in the RSTR 


2. Web Service Provider uses the SAML token from STS and requests access to resources hosted 


on the Web Service provider. 


3. The Web Service Provider validates the SAML token and provides access to the resources. 


4. When the token is nearing expiry, the Web service client sends a RST to WS-Trust STS to renew 


the token previously issued. The STS renews the validity of the token and sends a renewed 


token to the Web Service client for any further requests. 


5. Web Service client uses the renewed SAML token from STS and requests access to resources 


hosted on the Web Service provider. 


Authentication by Using SAML Tokens 


WS-Trust STS accepts SAML tokens issued by a third-party STS for authentication. The tokens can 


be in SAML 1.1 or SAML 2.0. 
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Workflow: 
1. The Web service client sends a RST to third-party STS. The third-party STS returns a SAML 
token to the client in the RSTR. 


2. The Web Service client uses SAML token issued by the third-party STS and requests WS-Trust 
STS to grant access to resources hosted on the Web Service Provider. 


3. WS-Trust STS authenticates the client using the third-party SAML token and issues a new SAML 
token. 


4. The Web Service client uses this new SAML token to get access to resources hosted on the 
Web Service Provider. 


5. The Web Service Provider validates the SAML token with WS-Trust STS. 


6. The Web Service client can access the resources on the Web Service Provider if the SAML 
token is valid. 


5.2.9.4 Configuring WS-Trust STS 


Before a Web service can invoke operations on STS, you must enable WS-Trust and configure it in 
Access Manager. This section discusses the following topics: 


¢ “Enabling WS-Trust” on page 569 
¢ “Configuring Access Manager for WS-Trust STS” on page 569 
¢ “Viewing STS Service Details” on page 569 
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Enabling WS-Trust 


Access Manager ships with only SAML 1.1, Liberty, and SAML 2.0 enabled by default. To use the 
WS-Trust protocol, you must enable it on Identity Server. 


To enable WS-Trust, perform the following steps: 


1 Click Devices > Identity Servers > Edit. 

2 In the Enabled Protocols section, select WS-Trust. 
3 Click OK. 

4 Update Identity Server. 


Configuring Access Manager for WS-Trust STS 
To configure WS-Trust STS, perform the following steps: 


1 Click Devices > Identity Servers > Edit. 
2 Select WS-Trust > STS Configuration. 
3 Specify the following details: 


Token Lifetime: Specify the duration in seconds for which the token is valid. The default value is 
360 seconds. 


Token Issuer: Specify the name of the issuer of the authentication token. 


Authentication Methods: Select methods that can be used for authentication at STS for WS- 
Trust. 


Select and move methods from Available Authentication Methods to Selected Authentication 
Methods. 


Tokens: Select the type of tokens that can be issued for authentication at STS for WS-Trust. 
SAML 1.1 and SAML 2.0 tokens are supported. If you select both token types, the token type 
configured in the service provider is returned. 


4 Click Apply. 


Viewing STS Service Details 


EndPoint URL is the SOAP endpoint of STS. The Web service client and Web service provider must 
be configured to these endpoints. 


In Administration Console Dashboard under Devices > Identity Servers > Edit > WS-Trust > 
EndPoint Summary, you can view the following STS EndPoint details: 


Service Name: The name of the STS service endpoint that is configured in the Web service client. 
Port Name: The port that STS implements. This is configured in the Web service client. 
MEX EndPoint URI: The MetadataExchange endpoint of STS. 


WSDL of STS Username authentication: WSDL location for username authentication. This file is 
used by applications that use the token service with username authentication. 


WSDL of STS SAML authentication: WSDL location for SAML. This file is used by applications that 
use the token service with SAML authentication. 
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Configuring Service Providers 


You need to configure Web service providers to accept tokens issued by an STS. The Web service 
provider uses an IssuedToken policy for the same. The IssuedToken policy is wrapped in WSDL. For 
a sample policy, see “A Sample WS-Policy for Web Service Providers” on page 574. 


Configuring a service provider includes adding a service provider domain and then adding a service 
provider in a configured domain. Access Manager also allows you to modify and delete configured 
service provider domains and service providers. 


+ 


+ 


+ 


+ 


+ 


+ 


“Adding a Domain and Assigning WS-Trust Operations” on page 570 
“Adding Web Service Providers” on page 570 

“Managing Service Provider Domains” on page 572 

“Managing Service Providers” on page 573 

“Modifying Service Providers” on page 573 

“A Sample WS-Policy for Web Service Providers” on page 574 


Adding a Domain and Assigning WS-Trust Operations 


1 
2 


Click Devices > Identity Servers > Edit > WS-Trust > Service Provider Domain. 


Click New > General to create a general domain. Selecting New > Office 365 creates an Office 
365 domain that can be configured for active authentication. For details on creating an Office 
365 domain, see “Configuring an Office 365 Domain By Using WS-Trust Protocol” on page 624 


Specify the following details: 
Name: Specify a name for the domain. 


WS-Trust Operations: Select operations in Available operations that WS-Trust STS performs 
for tokens and move these to Selected operations. 


The available operations are Issue, Validate, OnBehalfOf, ActAs and Renew. 


If you select OnBehalfOf and Act As the Available operations, additional configuration is 
required. For more information, see “Adding Policy for ActAs and OnBehalfOf’ on page 571 


Click Finish. Continue with creation of a trusted Service Provider. For more information, see 
Adding Web Service Providers 


Adding Web Service Providers 


This section discusses how to add service providers for WS-Trust STS. Adding a service provider 
includes adding service provider EndPoint URL, configuring trust certificates, selecting token types, 
and customizing attributes. 


Perform the following steps: 


Bh WN PF 


Click Devices > Identity Servers > Edit > WS-Trust > Service Provider Domain. 
Select the domain under which you want to configure a service provider. 

Click Service Provider > New. 

Specify the following details: 

Name: Specify a name for the service provider. 


Endpoint: Specify the SOAP endpoint location at the service provider to which SOAP messages 
are sent. 


Token Type: Select the type of token that the service provider will accept or validate. 
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Encrypt Proof Token Using: Import a certificate from the file system or paste content of the 
certificate here. This certificate must be configured in the Web service provider and is used for 
creating the subject confirmation in the SAML token. 


5 Click Finish. 
6 Select the Service Provider to define the Attributes and Authentication Response. For more 
information, see “Modifying Service Providers” on page 573 


Enabling Delegation and Impersonation 


By default, ActAs and OnBehalfOf requests are disabled in the Access Manager Identity Server. To 
enable delegation and impersonation, you must enable ActAs and OnBehalfOf by performing the 
following steps: 

1 Go to WS-Trust > Service Provider Domain. 


2 Click the service provider domain name for which you want to enable ActAs and OnBehalfOf 
operations. 


3 Under WS Trust Operations, select ActAs and OnBehalfOf in Available operations and move to 
Selected operations. 


4 Click OK. 
These operations are restricted to a set of privileged user accounts defined in the policy. You need to 
configure the allowed user accounts, who can perform ActAs and OnBehalfOf operations, in the 


nidconfig.properties file of each Identity Server installation. For more information, see “Adding 
Policy for ActAs and OnBehalfOf’ on page 571 


Configuring ActAs to Lookup Multiple User Stores 


For ActAs, the username on behalf of whom a client requests for a token must be present in the user 
store (eDirectory). The default implementation checks for this user only in the default user store. If 
you want to search the user in a different user store, perform the following steps: 
1 Click Devices > Identity Server > Edit > Local > Classes. 
2 Click New and specify the following details: 
Display name: Specify Find_By_Username 
Java class: Select Other 
Java class path: Specify com.novell.nidp.authentication.local. UserNameAuthenticationClass 
3 Click Next > Finish. 
4 Go to Local > Methods. 
5 Click New and select the Find_By Username class. 


For more information about how to configure an authentication method, see Section 5.1.3, 
“Configuring Authentication Methods,” on page 377. 


6 Go to WS-Trust > STS Configuration. Move this authentication method in the Selected 
Authentication Methods from Available Authentication Methods. 


Adding Policy for ActAs and OnBehalfOf 


You must add an policy to allow ActAs and OnBehalfOf operations. The default policy looks for a 
configuration of allowed user names from the nidpconfig. properties file. Allowed usernames are 
the user accounts that the intermediate Web service provider uses to authenticate with STS when 
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sending a request with ActAs or OnBehalfOf elements.For ActAs and OnBehalfOf, you must specify 
multiple username values separated with comma. If no value is specified, ActAs and OnBehalfOf are 


denied. 


1 Click Devices > Identity Servers > Edit > Options. 


2 Click New. 


3 Set the following properties based on your requirement: 


Property Type 


WSTRUST AUTHORIZATION ALLOWED 
ACTAS VALUES 


WSTRUST AUTHORIZATION ALLOWED 
ONBEHALF VALUES 


WSTRUST AUTHORIZATION ALLOWED 
VALUES 


4 Click OK > Apply. 


Property Value 


Specify the user names who can perform ACTas operations. 
Allowed user names are the user accounts that the 
intermediate web service provider uses to authenticate with 
STS when sending a request with Actas elements. 


Specify the user names who can perform OnBehalfOf 
operations. Allowed user names are the user accounts that 
the intermediate web service provider uses to authenticate 
with STS when sending a request with OnBehalfOf elements. 


Specify the user names who can perform both Actas and 
onBehalfOf operations. 


5 Restart Identity Server by running the following command: 


After upgrading Access manager, the configuration is set to default values. You must reconfigure 


the details after each upgrade. 


Linux: /etc/init.d/novell-idp restart 


Windows: net stop Tomcat7 


net start Tomcat? 


Managing Service Provider Domains 


The WS-Trust page allows you to create, modify, and delete service provider domains. This page lists 


all configured service provider domains. 


1 Click Devices > Identity Servers > Edit > WS-Trust > Service Provider Domains. 


The list of all configured service provider domains is displayed. 


2 Select one of the following actions: 


+ New: Select New > General to create a general domain. Selecting New > Office 365 creates 
a domain that can be configured for single sign-on to Office 365 services. For more on 
creating Office 365 domain, see “Adding a Domain and Assigning WS-Trust Operations” on 


page 570. 


+ Delete: Deletes the selected service provider domain. 


3 Click OK, then update Identity Server. 


4 Select the Service Provider domain to modify the following details: 


+ Name: Modify the name of the service provider domain. 


+ WS Trust Operations: Modify the list of selected WS-Trust operations. 


5 Click OK. 


Configuring Authentication 


Managing Service Providers 


Access Manager allows you to you to create, modify, and delete trusted service providers. The 
Service Providers page lists all configured service provider. 


1 Click Devices > Identity Servers > Edit > WS-Trust> Service Provider Domains> [name of the 
service provider domain] > Service Providers. 
The list of all configured service provider for the selected domain is displayed. 

2 Select one of the following actions: 


+ New: Launches the Create a Service Provider page. For more information, see “Adding 
Web Service Providers” on page 570. 


+ Delete: Deletes the selected service providers. 
3 Click OK. 


Modifying Service Providers 
1 Click Devices > Identity Servers > Edit > WS-Trust> Service Provider Domains> [name of the 
service provider domain] > Service Providers. 
The list of all configured service provider for the selected domain is displayed. 
2 Click the name of the service provider you want to edit. 
Configuration > Trust 
You can modify the following details: 
+ Name 
+ Endpoint 
+ Token Type 
+ Encrypt Proof Token Using 
For more information about these fields, see “Adding Web Service Providers” on page 570. 
Configuration > Attributes 


+ Select the Attribute Set and move attributes from the Available list to the Send with 
Authentication pane. This indicates the attributes that you want sent in an assertion to the 
service provider. 


Configuration > Authentication Response 
+ Specify a value for the name identifier. 


+ The persistent and transient formats are generated automatically. For the others, you 
can select an attribute. The available attributes depend upon the attributes that you 
have selected to send with authentication (see Configuring the Attributes Obtained at 
Authentication). If you do not select a value for the E-mail, Kerberos, X509, or 
Unspecified format, a unique value is automatically generated. 


IMPORTANT: In Access Manager 4.0 SP1, the SAML tokens with Name Identifier 
value other than username do not support ActAs, OnBehalfOf and SAML 
authentication operations. 


3 Click Apply. 
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A Sample WS-Policy for Web Service Providers 


You must modify WSDL of a Web service provider to include IssuedTokenPolicy that points to Access 
Manager WS-Trust STS. To modify WSDL, you need to add a WS-Policy with lssuedTokenElement. 
The following is a sample configuration: 


<wsp:Policy wsu:Id="<policy_name>"> 
<wsp:ExactlyOne> 
<wsp:All> 
<wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/ 
addressing/wsdl" wsp:Optional="false"/> 
<sc:KeyStore wspp:visibility="private" alias="xws-security-server"/> 
<sp:SymmetricBinding> 
<wsp:Policy> 
<sp:ProtectionToken> 
<wsp:Policy> 
<sp:IssuedToken sp:IncludeToken="http:// 
schemas. xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient"> 
<sp:RequestSecurityTokenTemplate> 
<t:TokenType>http://docs.oasis-open.org/wss/ 
oasis-wss-saml-token-profile-1.1#SAMLV1.1</t:TokenType> 
<t:KeyType>http://schemas.xmlsoap.org/ws/ 
2005/02/trust/SymmetricKkey</t :KeyType> 
<t:KeySize>256</t :KeySize> 
</sp:RequestSecurityTokenTemplate> 
<wsp:Policy> 
<sp:RequireInternalReference/> 
</wsp:Policy> 
<sp:Issuer> 
<wsaws :Address>https://namtest.com:8443/ 
nidp/wstrust/sts</wsaws :Address> 
<wsaws :Metadata> 
<wsx:Metadata> 
<wsx:MetadataSection> 
<wsx:MetadataReference> 
<wsaws:Address>https:// 
namtest.com:8443/nidp/wstrust/sts/mex</wsaws :Address> 
</wsx:MetadataReference> 
</wsx:MetadataSection> 
</wsx:Metadata> 
</wsaws :Metadata> 
</sp:Issuer> 
</sp:IssuedToken> 
</wsp:Policy> 
</sp:ProtectionToken> 
<sp:Layout> 
<wsp:Policy> 
<sp:Lax/> 
</wsp:Policy> 
</sp:Layout> 
<sp:IncludeTimestamp/> 
<sp:OnlySignEntireHeader sAndBody/> 
<sp:AlgorithmSuite> 
<wsp:Policy> 
<sp:Basic128/> 
</wsp:Policy> 
</sp:AlgorithmSuite> 
</wsp:Policy> 
</sp:SymmetricBinding> 
<sp:Wss11> 
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<wsp:Policy> 
<sp:MustSupportRefIssuerSerial/> 
<sp:MustSupportRefThumbprint/> 
<sp:MustSupportRefEncryptedKkey/> 
</wsp:Policy> 
</sp:Wssi1> 
<sp:Trust10> 
<wsp:Policy> 
<sp:MustSupportIssuedTokens/> 
<sp:RequireClientEntropy/> 
<sp:RequireServerEntropy/> 
</wsp:Policy> 
</sp:Trust10> 
</wsp:All> 
</wsp:ExactlyOne> 
</wsp:Policy> 


Configuring Web Service Clients 


Access Manager WS-Trust STS can be accessed from various Web service clients. The following 
sections provide example configurations and sample code snippets for CXF-based and Metro-based 
Web service clients: 


¢ “Configuring Apache CXF-based Web Service Clients” on page 575 
¢ “Configuring Metro-based Web Service Clients” on page 576 


Configuring Apache CXF-based Web Service Clients 


You can configure CXF-based Web service clients either programmatically or through XML 
configuration files. Below is a sample XML configuration. Add the following features to cxf. xml under 
the top-level beans section: 


<cxf :bus> 
<cxf : features> 
<cxf: logging /> 
<wsa:addressing /> 
</cxf: features> 
</cxf : bus> 


Define the STS client with its properties as follows: 


<jaxws:client name="{<your webservice target namespace>}WebServicePort" 
createdFromAPI="true"> 
<jaxws :properties> 
<entry key="ws-security.sts.client"> 
<bean class="org.apache.cxf.ws.security.trust.STSClient"> 
<constructor-arg ref="cxf" /> 
<property name="wsdlLocation" 
value="https://<your idp base url>nidp/wstrust/sts?wsdl" /> 
<property name="ServiceName" value="{http://www.netiq.com/nam-4-0/ 
wstrust}SecurityTokenService" /> 
<property name="endpointName" value="{http://www.netiq.com/nam-4-0/ 
wstrust}STS_ Port" /> 


<property name="wspNamespace" value="http://schemas.xmlsoap.org/ws/2004/ 


09/policy" /> 
<property name="properties"> 


Configuring Authentication 575 


5.2.9.7 


<map> 
<entry key="ws-security.username" value="<username to connect to idp>" 
/> 
<entry key="ws-security.password" value="<password>" /> 
<entry key="ws-security.encryption.properties" 
value="clientKeystore.properties" /> 
<entry key="ws-security.encryption.username" value="mystskey" /> 
<entry key="soap.force.doclit.bare" value="true" /> 
<entry key="soap.no.validate.parts" value="true" /> 
</map> 
</property> 
</bean> 
</entry> 
</jaxws:clien> 


You can configure ws-security.callback-handler to provide username and password 
programmatically. You can also configure global sts-client in cxf .xm1 that can be used across 
multiple Web services. 


For more information about configuring Apache CXF-based Web service clients, see Apache CFX 
(http://cxf.apache.org/docs/ws-trust.html). 


Configuring Metro-based Web Service Clients 
You can configure Metro-based clients through NetBeans (an integrated development environment). 


1 Create a Web service client project in NetBeans. 


2 Right click the project and click Create Web Service Client to create a STS client. Point the 
WSDL to http://<name of the identity provider server>:<port>/nidp/wstrust/sts ?wsdl. 


3 Configure the username and password to access WS-Trust STS. 


The user configured needs to get authenticated into Access Manager password-based 
authentication classes. You can also configure the Callback-based configuration in NetBeans to 
provide username and passwords dynamically. 


4 When you create a Web service client for your Web service, which is configured for STS-issued 
tokens, you need to specify the endpoint URL of WS-Trust STS in the Web service client 
properties. You can specify this in NetBeans by right clicking Web Service References> Web 
Service and selecting Secure Token Service. 


For more information about configuring Metro-based Web service clients, see To Specify an STS on 
the Service Side and To Specify an STS on the Client Side in Configuring A Secure Token Service 
(STS). 


Renew Token - Sample Request and Response 


+ “Renew Token - Sample Request” on page 577 
+ “Renew Token - Sample Response” on page 579 
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Renew Token - Sample Request 


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> 
<soap:Header> 
<Action xmlns="http://www.w3.org/2005/08/addressing">http://docs.oasis- 
open. org/ws-sx/ws-trust/200512/RST/Renew</Action> 
<MessageID xmlns="http://www.w3.org/2005/08/addressing">urn: uuid: 9cfedcee- 
2ebf -47e0-a24a-45281d785136</MessageID> 
<To xmlns="http://www.w3.org/2005/08/addressing">https:// 
namsb.blr.novell.com:443/nidp/wstrust/sts</To> 
<ReplyTo xmlns="http://www.w3.org/2005/08/addressing"> 
<Address>http: //www.w3.org/2005/08/addressing/anonymous</Address> 
</ReplyTo> 
<wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis- 
open. org/wss/2004/01/oasis -200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http:/ 
/docs.oasis-open.org/wss/2004/01/oasis -200401-wss-wssecurity-utility-1.0.xsd"> 
<wsu:Timestamp wsu:Id="TS-1"> 
<wsu:Created>2014-02-10T23:36:42Z</wsu:Created> 
<wsu: Expires>2014-02-10T24: 36:42Z</wsu:Expires> 
</wsu: Timestamp> 
<wsse:UsernameToken wsu: Id="UsernameToken-2"> 
<wsse: Username>admin</wsse:Username> 
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis- 
200401 -wss -username-token-profile-1.0#PasswordText">novell</wsse:Password> 
</wsse:UsernameToken> 
</wsse:Security> 
</soap:Header> 
<soap : Body> 
<wst:RequestSecurityToken xmlns:wst="http://docs.oasis-open.org/ws-sx/ws- 
trust/200512" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss- 
wssecurity-secext-1.0.xsd"> 
<wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Renew</ 
wst :RequestType> 
<wst:TokenType>urn:oasis:names:tc:SAML:2.0:assertion</wst : TokenType> 
<wst:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/ 
Symmetrickey</wst : KeyType> 
<wst: Entropy> 
<wst:BinarySecret Type="http://docs.oasis-open.org/ws-sx/ws-trust/ 
200512/Nonce">200dAaghr BJqbouiQTf 7D2pxXtXRo36Wi/yswGeoq7iQ=</wst : BinarySecret> 
</wst :Entropy> 
<wst :RenewTarget> 
<saml2:Assertion ID="nstsa657b5f4-9bf0-45b7 -9875-07eeb6d65196" 
IssueInstant="2014-05-26T10:33:50.564Z" Version="2.0" xmlns:ds="http://www.w3.org/ 
2000/09/xmldsig#" xmlns:exc14n="http://www.w3.org/2001/10/xml-exc-c14n#" 
xmlns:sam12="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xenc="http://www.w3.org/ 
2001/04/xmlenc#" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:ns10="http:// 
www.w3.org/2000/09/xmldsig#" xmlns:nsi3="http: //www.w3.org/2001/10/xml-exc-ci4n#" 
xmlns:ns3="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" 
xmlns:ns5="http://docs.oasis-open.org/ws-sx/ws-trust/200512/"_ xmlns:ns9="http:// 
schemas. xmlsoap.org/ws/2006/02/addressingidentity" xmlns:sc="http://docs.oasis- 
open. org/ws-sx/ws-secureconversation/200512" xmlns:trust="http://docs.oasis- 
open.org/ws-sx/ws-trust/200512" xmlns:wsa="http://www.w3.org/2005/08/addressing" 
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wst="http:// 
schemas .xmlsoap.org/ws/2005/02/trust" xmlns:wsu="http://docs.oasis-open.org/wss/ 
2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:S="http://www.w3.org/ 
2003/05/soap-envelope" xmlns:wsseii="http://docs.oasis-open.org/wss/oasis-wss- 
wssecurity-secext-1.1.xsd"> 
<saml12:Issuer>https://namsb.blr.novell.com/nidp/wstrust/sts</ 
saml12:Issuer> 
<ds:Signature> 
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<ds:SignedInfo> 
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/ 
10/xml1-exc-c14n#"/> 
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/ 
xmldsig#rsa-shai"/> 
<ds:Reference URI="#nstsa657b5f4-9bf0-45b7 -9875-07eeb6d65196"> 
<ds:Transforms> 
<ds:Transform Algorithm="http://www.w3.org/2000/09/ 
xmldsig#enveloped-signature"/> 
<ds:Transform Algorithm="http://www.w3.org/2001/10/xm1- 
exc-c14n#"/> 
</ds:Transforms> 
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/ 
xmldsig#shai"/> 
<ds :DigestValue>Z3S4qxz2wRvOk5np2R6ENKIF9pk=</ 
ds:DigestValue> 
</ds:Reference> 
</ds:SignedInfo> 


<ds:SignatureValue>ZxeqeuD7NXfFNRPiaYY3v2Nfo9vTx+ceASiAFBDZOf awGcZHBT OeYU+AQM99VdX1 
GCBCdwq09qQR8 
2WP71mzREC6ndg+8g/zZJ6UH+JzsfO5h1xCAu7d7 fg5qP5/BP++x8vU1pUQ32D8daxx+GIwuZj10s 
8KhdbgLReYSWyX6PVOUbj bnAtDFaBTTJ51pEqHdK7FGUiISXg679016BT JSS/V2bBOrx7cZGRGte 
PMBGz19qXOr ZoeNpLJFpJi23+/wAYaqzz0kyRGeyAODeOugsqw2XRvUPciaYhbqqOraFUfmpyspC 
07C1zwsvn01ih1gVX/1DBwfLokrBeijsG3FN3Hg==</ds : SignatureValue> 
<ds:KeyInfo> 
<ds:X509Data> 
<ds:X509Certificate>MIIFBDCCAtygAwIBAgIkAhwR/ 
6b9CQnrHMhxuBSYqOCbHugRb+e4U/9 jwi9kAg IwCZKCMAOGCSqG 
SIb3DQEBBQUAMDEXGjAYBgNVBASTEU9yZ2FuaxphdGlvbmFs IENBMRMWEQYDVQQKFApuYW1izY190 
CmV1MB4XDTEOMDUyMTE4NTQwMVoXDT LOMDUyMTE4NTQwMVowHZEdMBSGA1UEAXMUbmFtc21uYmxy 
Lm5vdmVsbC5 j b20wggEiMAOGCSqGSIb3DQEBAQUAA4 IBDWAWggEKAOIBAQDRTSdCFBM3ImpIyRAj 
OdFFEYbC/ykQUEZFwGp62BAUxoL10pmDZyxpbqIh+1462GFByuCvkLOhnelOGV61i/cTAbaHko7h 
T7cfUC3N4kmhnc3IXwgjodRIXMlaUSYDYd79guyVjGObrOWJMxJxvmleo3p8bFzPLnpkEdJ7c8HM 
BRqckecaGT8nbpm1iKGZFAStrRRTryu2aG670FP3+MHWZmydqLlvrKinCfe+7D1pOUwA13sSgMs1lf 
6UCI4E50gn6pQ26rctGkKrBsFfrx76t6ESZuagFlWS+YA11cWS3ir tihTOp2GsoxcJzq+IvHosHY+ 
pvr t4gcJiZJIN6P3e6yrrAgMBAAGj ggIUMI ICEDAdBgNVHQ4EFgQUpSkUiviZFQ7yIDLb9sJT+mZH 
kngwHwYDVROj BBgwFoAUfFFLP7EF6tU2U2qquPNTVLDdV7e8wggHMBgt ghkgBhvg3AQkEAQSCAbsw 
ggG3BAIBAAEB/xMdTm92ZWxsIFNLY3VyaXR5IEFOdHJpYnVOZShObSkWQ2hOdHAG6Ly9kZXZ1bG9w 
ZXIubm92ZwxsLmNvbS9yZxXBvc210b3J5L2FOdHJpYnVOZXMVY 2VydGFOdHJZX3YxMC5o0dGOwggF I 
OBOBAQAWCDAGAgEBAgFGMAgwBg IBAQIBCg IBaaEaAQEAMAgwBg IBAQIBADAIMAYCAQECAQACAQCi 
Bg IBFwEB/60CAQSgWAIBAg ICAP8CAQADDQCAAAAAAAAAAAAAAAADCQCAAAAAAAAAADAYMBACAQAC 
CH//////////AQEAAgQG8N9OIMBgWEAIBAAIIF/////////8BAQACBAbw30ihWAIBAg ICAP8CAQAD 
DQBAAAAAAAAAAAAAAAADCQBAAAAAAAAAADAYMBACAQACCH//////////AQEAAGQR/6b9MBgwEAIB 
AAIIF/////////8BAQACBBH/pv2iT ] BMAGECAgEAAgIA/wMNAIAAAAAAAAAAAAAAAAMJATAAAAAA 
AAAAMBIWEAIBAAIILf/////////8BAQAWEj AQAGEAAGh//////////WEBADANBgkghkiG9wOBAQUF 
AAOCAQEAbDAOAdHm5pV6cEwSy0oB3aJfalegMYPLAUTNK9ajhez9PIHPGSQZNxXTRbj 3eV9P+ueP7 j 
18AFVR3Ej 4eA7S115kPGUSXhwM6VhSIsCn+x+HbpnFdwJdu5EvEr j TIbbj RU/4wTRCqKe71loFqKs 
rH+BGNuUJw1612PM+wJ+sajX7ktzP8rk8CF+cTOe8ggFcEuJ4igliMMkVbuliRTggRmpcILNFk57 
QdmySozjVok10VQ0zIGcAggPBSZeCumNNP8mQTAmvnwWwGOcTvDIkMkCV1AZCCOWKOdWM53JZD/aa 
tHay9w8QWoUU5c Jo8B+uSm2vN+53PdtMKWOxhJcxtXpkKKg==</ds : X509Certificate> 
</ds:X509Data> 
</ds:KeyInfo> 
</ds:Signature> 
<saml12:Subject> 
<saml2:NameID NameQualifier="">admin</sam12 :NameID> 
<saml12:SubjectConfirmation 
Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/> 
</saml12:Subject> 
<sam12:Conditions NotBefore="2014-05-261T10:33:50.564Z" 
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NotOn0rAfter="2014-05-26T10:35:50.564Z"> 
<saml2:AudienceRestriction> 
<sam12:Audience>http://164.99.184.228:8080/doubleit/services/ 
doubleit</sam12:Audience> 
</saml12:AudienceRestriction> 
</sam12:Conditions> 
<saml12:Advice/> 
<saml12:AuthnStatement AuthnInstant="2014-05-26T10:33:50.564Z"> 
<saml2:AuthnContext> 


<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:1.0:am:password</ 
saml12:AuthnContextClassRef> 
</saml12:AuthnContext> 
</sam12:AuthnStatement> 
<sam12:AttributeStatement> 
<saml2:Attribute AttributeName="emailaddress" 
AttributeNamespace="http://schemas.xmlsoap.org/ws/2005/05/identity/claims" 
Name="emailaddress" NameFormat="http://schemas.xmlsoap.org/ws/2005/05/identity/ 
claims"> 
<saml12:AttributeValue>admin@idp.com</saml2:AttributeValue> 
</saml12:Attribute> 
</sam12:AttributeStatement> 
</saml12:Assertion> 
</wst :RenewTarget> 
</wst :RequestSecurityToken> 
<ns:RequestSecurityToken xmlns:ns="http://docs.oasis-open.org/ws-sx/ws-trust/ 
200512/"/> 
</soap : Body> 
</soap:Envelope> 


Renew Token - Sample Response 


<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsse11="http:/ 
/docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" xmlns:wsse="http:// 
docs.oasis-open.org/wss/2004/01/oasis -200401-wss-wssecurity-secext-1.0.xsd" 
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis -200401-wss-wssecurity- 
utility-1.0.xsd" xmins:xs="http://www.w3.org/2001/XMLSchema"> 
<S:Header> 
<Action S:mustUnderstand="true" xmlns="http://www.w3.org/2005/08/ 
addressing">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/RenewFinal</ 
Action> 
<MessageID xmlns="http://www.w3.org/2005/08/addressing">uuid: f41d7aeb-6f67 - 
4df3-9fe4-e160889b7efb</MessageID> 
<RelatesTo xmlns="http://www.w3.org/2005/08/addressing">urn: uuid: 9cfedcee- 
2ebf -47e0-a24a-45281d785136</RelatesTo> 
<To xmlns="http://www.w3.org/2005/08/addressing">http: //ww.w3.org/2005/08/ 
addressing/anonymous</To> 
<wsse:Security S:mustUnderstand="true"> 
<wsu:Timestamp wsu:Id="_1" xmlns:nsi5="http://docs.oasis-open.org/ws-sx/ 
ws-secureconversation/200512" xmlns:nsi4="http://schemas.xmlsoap.org/soap/ 
envelope/"> 
<wsu:Created>2014-05-26T10:35:41Z</wsu:Created> 
<wsu:Expires>2014-05-26T10: 40: 41Z</wsu:Expires> 
</wsu: Timestamp> 
</wsse:Security> 
</S:Header> 
<S:Body> 
<trust:RequestSecurityTokenResponse xmlns:ns10="http://www.w3.org/2000/09/ 
xmldsig#" xmlns:ns13="http://www.w3.org/2001/10/xml-exc-c14n#" xmlns:ns3="http:// 
docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" xmlns:ns5="http:// 
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docs.oasis-open.org/ws-sx/ws-trust/200512/" xmlns:ns9="http://schemas.xmlsoap.org/ 
ws/2006/02/addressingidentity" xmlns:sc="http://docs.oasis-open.org/ws-sx/ws- 
secureconversation/200512" xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/ 
200512" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsp="http:// 
schemas. xmlsoap.org/ws/2004/09/policy" xmlns:wst="http://schemas.xmlsoap.org/ws/ 
2005/02/trust"> 
<trust:TokenType>urn:oasis:names:tc:SAML:2.0:assertion</trust : TokenType> 
<trust:RequestedSecurityToken> 
<saml2:Assertion ID="nstsa657b5f4-9bf0-45b7 -9875-07eeb6d65196" 
IssueInstant="2014-05-26T10:35:41.072Z" Version="2.0" xmlns:ds="http://www.w3.org/ 
2000/09/xmldsig#" xmlns:exc14n="http://www.w3.org/2001/10/xml-exc-c14n#" 
xmlns:sam12="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xenc="http://www.w3.org/ 
2001/04/xmlenc#"> 
<saml12:Issuer>https://namsb.blr.novell.com/nidp/wstrust/sts</ 
saml2:Issuer> 
<ds:Signature> 
<ds:SignedInfo> 
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/ 
10/xml-exc-c14n#"/> 
<ds:SignatureMethod Algorithm="http: //www.w3.org/2000/09/ 
xmldsig#rsa-shai"/> 
<ds:Reference URI="#nstsa657b5f4-9bf0-45b7 -9875-07eeb6d65196"> 
<ds:Transforms> 
<ds:Transform Algorithm="http://www.w3.org/2000/09/ 
xmldsig#enveloped-signature"/> 
<ds:Transform Algorithm="http://www.w3.org/2001/10/xm1- 
exc-c14n#"/> 
</ds:Transforms> 
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/ 
xmldsig#sha1"/> 
<ds :DigestValue>bX5LSf roOHkupLSMKU/V+x39P+g=</ 
ds:DigestValue> 
</ds:Reference> 
</ds:SignedInfo> 
<ds:SignatureValue>QLRRXQ4TzZTgM9mVa5UF1p7YRQRVLP/ 
h3pyPOKVZZXcbCfDmtT4b0141qFhNoXL+Ym2iu2V1iMIC5I 
TRSt6D/y6pfs4/nChMrOuk5spMZYLBee+OPd1GYhfLGzyh/AONZGsoVrHfi/LItMeTp4mMVmk/hTp 
8yTWbOr79Ssz5TEbwJ/NkqFxXxa9xf fheaT ySOFNXQYu3tLirdp7Zaq5BR7myeOOhuo6gBT ShHTXM 
FGPYMu/SyOkapqTBWHUbwt 8FzysBEgELZdquhuvtiNOfHqkwAbyp5vExj j rYx106Z7Fu3LnDSqt+m 
hI9S+VLSibBR2XgNofhw/bFVBboYkzZDT6Ipmg==</ds : SignatureValue> 
<ds:KeyInfo> 
<ds:X509Data> 
<ds:X509Certificate>MIIFBDCCAtygAwIBAgIkAhwR/ 
6b9CQnrHMhxuBSYqOCbHugRb+e4U/9 jwi9kAg IwCZKCMAOGCSqG 
SIb3DQEBBQUAMDExGjAYBgNVBASTEU9yZ2FuaxphdGlvbmFs IENBMRMWEQYDVQQKFApuYwW1izY190 
CmV1MB4XDTEOMDUyMTE4NTQwMVoXDT LOMDUyMTE4NTQwMVowHZEdMBSGA1UEAXMUbmFtc2IuYmxy 
Lm5vdmVsbC5 j b20wggEiMAOGCSqGSIb3DQEBAQUAA4 IBDWwAWggEKAOIBAQDRTSdCFBM3ImpIyRAj 
OdFFEYbC/ykQUEZFwGp62BAUxoL10pmDZyxpbqIh+1462GFByuCvkLOhnel0GV61i/cTAbaHko7h 
T7cfUC3N4kmhnc31XwgjodRIXMlaUSYDYd79guyVjGObrOWJMxJxvmleo3p8bFzPLnpkEdJ7c8HM 
BRqckecaGT8nbpm1ikKGZFAStrRRTryu2aG670FP3+MHWZmydqLlvrKinCfe+7D1pOUWA13sSgMs1f 
6UCT4E50gn6pQ26rctGKrBsFfrx76t6ESZuagFlWS+YA11cWS3ir tihTOp2GsoxcJzq+IvHoSHY+ 
pvr t4gcJiZJIN6P3e6yr rAgMBAAGj ggIUMI ICEDAdBgNVHQ4EFgQUpSkUiviZFQ7yIDLb9sJT+mZH 
kngwHwYDVROj BBgwFoAUfFLP7EF6tU2uU2qquPNTVLDdV7e8wggHMBgt ghkgBhvg3AQkEAQSCAbsw 
ggG3BAIBAAEB/xMdTm92ZWxsIFNLY3VyaXR5IEFOdHJpYnVOZShObSkWQ2hOdHAG6Ly9kZXZ1bG9wW 
ZXIubm92ZwxsLmNvbS9yZxXBvc210b3J5L2FOdHJpYnVOZXMvVY 2VydGFOdHJZX3YxMC5o0dGOwggFI 
OBOBAQAWCDAGAgEBAgFGMAgwBg IBAQIBCg IBaaEaAQEAMAgwBg IBAQIBADAIMAYCAQECAQACAQCi 
Bg IBFwEB/60CAQSgWAIBAg ICAP8CAQADDQCAAAAAAAAAAAAAAAADCQCAAAAAAAAAADAYMBACAQAC 
CH//////////AQEAAgQG8N9OIMBgWEAIBAAIIF/////////8BAQACBAbw30ihWAIBAg ICAP8CAQAD 
DQBAAAAAAAAAAAAAAAADCQBAAAAAAAAAADAYMBACAQACCH//////////AQEAAGQR/6b9MBgwEAIB 
AAIIF/////////8BAQACBBH/pv2iT ] BMAGECAgEAAgIA/wMNAIAAAAAAAAAAAAAAAAMJAITAAAAAA 
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AAAAMBIWEAIBAAIIF/////////8BAQAWE] AQAGEAAgGh//////////wWEBADANBgkqhkiG9wOBAQUF 
AAOCAQEAbAOAdHm5pV6cEwSy0oB3aJfaLegMYPLAUTNK9aj hez9PIHPGSQZNxTRbj 3eV9P+ueP7 j 
18AFVR3Ej 4eA7S115kPGUSXhwM6VhSIsCn+x+HbpnFdwJdu5EvEr j TIbbj RU/4wTRCqKe71loFqKs 
rH+BGNuUJw1612PM+wJ+sajX7ktzP8rk8CF+cTOe8ggFcEuJ4igliMMkVbuliRTggRmpcILNFk57 
QdmySozjVok10VQ0zIGcAggPBSZeCumNNP8mQTAmvnwwGOcTVDIkMkCV1AzZCCOWKOdWM53JZD/aa 
tHay9w8QWoUU5c Jo8B+uSm2vN+53PdtMKwWOxhJcxtXpkKKg==</ds : X509Certificate> 
</ds:X509Data> 
</ds:KeyInfo> 
</ds:Signature> 
<saml12:Subject> 
<saml2:NameID NameQualifier="">admin</sam12 :NameID> 
<saml2:SubjectConfirmation 
Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/> 
</saml2:Subject> 
<saml12:Conditions NotBefore="2014-05-26T10:35:41.072Z" 
NotOnorAfter="2014-05-26T10:37:41.072Z"> 
<saml2:AudienceRestriction> 
<sam12:Audience>http://164.99.184.228:8080/doubleit/services/ 
doubleit</saml12:Audience> 
</sam12:AudienceRestriction> 
</sam12:Conditions> 
<saml2:Advice/> 
<saml12:AuthnStatement AuthnInstant="2014-05-26T10:33:50.564Z"> 
<saml2:AuthnContext> 


<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:1.0:am:password</ 
saml12:AuthnContextClassRef> 
</sam12:AuthnContext> 
</sam12:AuthnStatement> 
<sam12:AttributeStatement> 
<saml2:Attribute AttributeName="emailaddress" 
AttributeNamespace="http://schemas.xmlsoap.org/ws/2005/05/identity/claims" 
Name="emailaddress" NameFormat="http://schemas.xmlsoap.org/ws/2005/05/identity/ 
claims"> 
<saml12:AttributeValue xmlns:soap="http://www.w3.org/2003/05/ 
soap -envelope">admin@idp.com</sam12:AttributeValue> 
</saml12:Attribute> 
</sam12:AttributeStatement> 
</saml12:Assertion> 
</trust :RequestedSecurityToken> 
<trust:Lifetime> 
<wsu: Created>2014-05-26T10:35:41.071Z</wsu:Created> 
<wsu:Expires>2014-05-26T10:37:41.071Z</wsu:Expires> 
</trust:Lifetime> 
</trust :RequestSecurityTokenResponse> 
</S:Body> 
</S:Envelope> 


5.2.10 Configuring OAuth and OpenID Connect 


OAuth 2.0 is an open protocol to allow secure authorization. It enables users to allow third-party client 
to access users’ private resources. Users do not need to share their credentials. The third-party 
clients can be web applications, mobile phones, handheld devices, and desktop applications. OAuth 
provides a method to issue Access tokens to third-party client applications with the user's approval. 
The third-party client application can then use the Access token to access protected resources 
hosted by the resource server. 


OAuth allows users to control the access to web resources by scope, action, and time. 
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Access Manager uses OpenID Connect along with OAuth. OpenID Connect implements a single 
sign-on protocol on top of the OAuth authorization process. It allows client applications to verify the 
identity of a user based on the authentication performed by Identity Server (authorization server). It 
also allows client applications to obtain a user’s basic profile information. 


See Appendix C, “OAuth versus Other Protocols,” on page 1469 for differences among OAuth and 
other single sign-on protocols. 

¢ Section 5.2.10.1, “How OAuth Helps,” on page 582 

¢ Section 5.2.10.2, “OAuth Terminology,” on page 582 

¢ Section 5.2.10.3, “How OAuth Works,” on page 583 

¢ Section 5.2.10.4, “Why Use OpenID Connect,” on page 586 

¢ Section 5.2.10.5, “OAuth Scenarios,” on page 587 

¢ Section 5.2.10.6, “OAuth Implementation Flow,” on page 589 

¢ Section 5.2.10.7, “OAuth Authorization Grant,” on page 592 

¢ Section 5.2.10.8, “OpenID Connect Authentication Flows,” on page 594 

¢ Section 5.2.10.9, “Managing OAuth and OpenID Connect,” on page 595 

¢ Section 5.2.10.10, “Configuring Access Gateway for OAuth,” on page 604 

¢ Section 5.2.10.11, “Viewing Endpoint Details,” on page 608 

¢ Section 5.2.10.12, “OAuth and OpenID Connect Audit Events,” on page 608 

¢ Section 5.2.10.13, “Enabling Logging for OAuth and OpenID Connect,” on page 609 

¢ Section 5.2.10.14, “Managing Clients Applications by Using REST API,” on page 609 


¢ Section 5.2.10.15, “Managing OAuth 2.0 Resource Server and Scope by Using REST API,” on 
page 612 


¢ Section 5.2.10.16, “End User Operations,” on page 615 
¢ Section 5.2.10.17, “Configuring the Demo OAuth Application,” on page 615 


5.2.10.1 How OAuth Helps 


OAuth addresses the following security concerns: 


+ To provide access to protected resources, users share their credentials in clear-text with third- 
party applications. Potential security breaches that can result from the ability of third-party 
applications to store a user's credentials for future use. 


¢ Security issues associated with password authentication. 


¢ The inability of resource owners to restrict a client application's access to protected resources for 
a specified duration or to limit the client application's access to a subset of resources. 


¢ The inability of resource owners to revoke a client application's access to a specific client 
application. 


5.2.10.2 OAuth Terminology 


The following list includes frequently used terms in an OAuth flow: 


OAuth Roles 


+ Resource Owner: Grants access to a protected resource. 
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5.2.10.3 


+ Resource Server: Hosts the protected resources. It accepts and responds to requests by using 
Access tokens. 


¢ Client: An application that requests access to protected resources on behalf of the resource 
owner with the resource owner's authorization. A client application, for example, can be a 
gaming application. 


+ Authorization Server: Generates Access tokens for a client application after authenticating the 
resource owner and obtaining authorization from the resource owner. The authorization server in 
Access Manager is Identity Server. 


OAuth Credentials and Tokens 
+ ID Token: JSON Web Token (JWT): Contains a user’s claims such as identity, email address, 
and other profile information. It also specifies the issuing authority. 


+ Access Token: Required to access protected resources. Contains the attributes, such as scope 
and duration, that are granted by the authorization server. 


+ Refresh Token: Used to obtain Access tokens. The authorization server issues a Refresh token 
to the client application. Client applications use this token to obtain a new Access token when 
the current Access token expires or is no longer valid. 


¢ Client Key and Secret: A client application uses a client key to identify itself to a service 
provider. A client application uses the client secret to establish the ownership of the client key. 
The authorization server assigns a key and a secret to a client application while registering it. 


OAuth Endpoints 
¢ Authorization Endpoint: Client applications use this endpoint to interact with the resource 
owner and obtain an authorization grant. It is located on an authorization server. 


¢ Token Endpoint: Client applications use this endpoint to obtain an Access token by providing 
their authorization grant or Refresh token. It is also located on an authorization server. 


How OAuth Works 


You can configure OAuth with Access Manager in one of the ways based on the following 
requirements: 


+ Ifthe web applications validate the Access token before allowing a client application accesses to 
resources. 

+ If Access Gateway validates the Access token on behalf of web applications. 

+ If Access Gateway injects the Access token on behalf of web applications. 


Web applications validate an Access token before allowing a client application to access 
resources 


Identity Server (authorization server) issues an Access token and web applications validate the token 
before granting a client application to access resources. This configuration is suitable in the following 
scenarios: 

+ Web server authentication 

e Accessing resources without using owner’s credentials 

+ RESTful applications security 

¢ Mobile authentication 


For more information about these scenarios, see “OAuth Scenarios” on page 587. 
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Figure 5-16 The following diagram illustrates the OAuth flow: 
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1. The client application requests authorization from the user (resource owner). Client applications 
can make the authorization request directly to the resource owner or through the authorization 
server (Identity Server) as an intermediary. 


2. The client application receives an authorization grant from the authorization server. An 
authorization grant represents the resource owner's authorization. The user communicates the 
authorization by using one of four grants types (see “OAuth Authorization Grant” on page 592) or 
by using an extension grant. 


3. The client application authenticates itself at the authorization server, sends the authorization 
grant, and requests an Access token. 


4. The authorization server authenticates the client application and validates the authorization 
grant. The authorization server issues an Access token for a valid grant. 


5. The client application requests the resource server to provide access to the protected resource 
and authenticates this by presenting the Access token. 


6. The resource server accepts the request for a valid token. 
Access Gateway validates the Access token on behalf of web applications 


This configuration is suitable when client applications want to access resources on legacy web 
applications. See “Legacy Web Applications Security” on page 589 for details about when to use this 
configuration. 
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Figure 5-17 The following diagram illustrates the workflow: 
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1 Aclient application requests access to a web resource and provides authentication details to 
Identity Server. 


2 Identity Server authenticates the client application, gets the user’s consent, generates an OAuth 
token, and sends the token to the client application. 


The client application provides the token to Access Gateway. 
Access Gateway sends the token to Identity Server for validation. 
If the token is not valid, Access Gateway returns a 401 error. 


on F&F WwW 


If the token is valid, Access Gateway performs the following tasks: 
6a Executes the authorization policy, if configured, based on OAuth scopes or claims. 


6b Sends user attributes and grants details provided to the client application to the web 
application by using the Identity Injection policy, if configured. 


7 The resource server returns a response to Access Gateway and Access Gateway sends this 
response to the client application. 


Access Gateway injects the Access token on behalf of web applications 


This configuration is used when Access Gateway injects the Access tokens into the authorization 
header. 
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Figure 5-18 The following diagram illustrates the workflow: 
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1 The user sends request to access a web application protected by Access Gateway. 
2 Access Gateway redirects the user to Identity Server, which prompts for user authentication. 


3 On successful authentication, Access Gateway shares the session details with Identity server to 
fetch the OAuth token. 


4 Identity server authenticates the session details and issues an Access token to Access Gateway. 
5 Access Gateway injects the Access token into the authorization header. 


Why Use OpenID Connect 


OAuth allows users to authorize client applications to access users' protected resources through an 
Access token. The Access token does not contain any information about a user's identity. Hence, a 
client application does not know who the user is. A client application also does not know if the 
authorization server has issued the access token to it or to any other relying party. 


OpenID Connect builds on OAuth and provides solutions for OAuth’s limitations. It issues an ID token 
that contains signed assertions about the user. Client applications can verify the ID token and obtain 
additional details about the user. The ID token also contains information about the issuing authority, 
the intended client application, time of the token created, and the token expiration time. 


OpenID Connect Claims 


A client application can obtain information about a user and authentication events through claims. A 
claim contains information about a user such as phone number, first name, and last name. 


586 Configuring Authentication 


5.2.10.5 


OAuth Scenarios 


This section describes the following basic scenarios supported by OAuth: 


¢ “RESTful Applications Security” on page 587 

e “Accessing Resources without Using the Resource Owner’s Credentials” on page 587 
e “Web Server Authentication” on page 587 

¢ “Mobile Authentication” on page 589 

+ “Legacy Web Applications Security” on page 589 


RESTful Applications Security 


OAuth provides a way to secure REST APIs. For example, an enterprise acme.com exposes REST 
APIs that provide various functions. Using OAuth, acme.com can provide secure authorization control 
on APIs to ensure that the right people have access to these APIs. In addition, they can also enable 
applications to call APIs on behalf of a user. acme.com can also revoke access to an API even if an 
application uses it. 


See Appendix B, “SOAP versus REST API,” on page 1467 to learn the differences between SOAP 
and REST API. 


Accessing Resources without Using the Resource Owner’s Credentials 


In a typical web authentication model, a client application uses the resource owner's credentials to 
access the resource owner's information that is hosted on a server. OAuth allows a client application 
to access resources that are controlled by the resource owner and provides a method to obtain 
permission from the resource owners to access their resources. The resource owners provide this 
permission in the form of a token and a matching shared-secret. The resource owner does not need 
to share credentials with the client application. Tokens are issued with a restricted scope and limited 
life. 


For example, a user named Alice has installed a gaming application that runs in her browser and 
uses OAuth for accessing a social site at www. example .com. The gaming application updates scores 
in a database at www. example . com. The gaming application is registered with the social site and has 
an identifier. Alice has registered with the social site for identification and authentication. To upload 
Alice's scores, the gaming application accesses the score database when Alice authorizes it. When 
Alice accesses the page from the redirect URI in the game application, the authorization server sends 
the client ID, password, and authentication code received in the redirect request parameters to 
www.example.com, which in turn returns an Access token to the game application. The gaming 
application sends the token to www. example . com to access Alice’s resources. www. example verifies 
the token and grants the gaming application access to Alice’s account for updating the scores. 


NOTE: This example is derived from the OAuth RFC document. 


Web Server Authentication 


To access the user data of other sites, third-party applications seek user’s credentials (user names 
and passwords). Sharing passwords may result in a security breach. OAuth enables third-party 
applications to access a user’s information without using the users’ passwords. OAuth also provides 
a way to grant limited access. For example, a user (resource owner) can allow a printing service 
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(client application) to access private photos stored at a photo sharing service (server), without sharing 
credentials with the printing service. Instead, the user authenticates directly with the photo sharing 
service that issues the printing service delegation-specific credentials. 


For example, a user named Alice accesses an application running on a web server at 
www.printphotos.example and instructs it to print her photographs that are stored on a server at 
www.storephotos.example. The application at ww.printphotos.example receives Alice's 
authorization consent for accessing her photographs without learning her authentication credentials 
of www. storephotos. example. 


The following diagram illustrates the workflow of the web server authentication: 
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www.storephotos.example 


NOTE: This example is derived from the OAuth RFC document. 
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Mobile Authentication 


Applications on a mobile device request for authentication and the web server redirects you to the 
authorization server (Identity Server) to authenticate and authorize the server to access your data. 
When you approve, the web server receives an Access token as part of the redirect URL. After the 
authorization server grants the token, the application can access the protected data with the Access 
token. Less confidential applications, such as mobile clients or thick clients use this authentication. 


Legacy Web Applications Security 


Scenario 1: OAuth enables client applications including thick clients, mobile, and OAuth enabled 
browser-based applications to access resources available on legacy web applications. In this 
scenario, Access Gateway validates the token on behalf of web applications. You do not need to 
modify web applications to understand the OAuth flow. 


Scenario 2: In addition to scenario 1, OAuth also supports the following scenario: 


Let suppose an enterprise acme.com has a multi-tier application: a front-end web application utilizing 
services from web service layers. The enterprise wants to protect these services and applications 
using OAuth and thereby need to place the RESTful API endpoints behind Access Gateway. The 
applications need to be modified to fetch OAuth token from Identity server. To minimize this change, 
Access Manager has the ability to enable Access Gateway to fetch OAuth tokens on behalf of the 
application and pass it over to the application via HTTP header. Now, the application can simply take 
the token from the header and use it to invoke the web service. 


OAuth Implementation Flow 


The following diagrams depict the implementation flow of OAuth in Access Manager: 


¢ OAuth Implementation without using Access Gateway 


+ OAuth Implementation using Access Gateway 


NOTE: Access Manager uses variable length Access tokens and authorization codes. The client 
applications and web servers must not assume any fixed size of tokens and codes and must allocate 
necessary memory to handle the token. Token size depends on the size of scope names. Some 
servers may have size limitations on query string and HTTP headers. Ensure that an application uses 
only necessary scopes to avoid any issue. 
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OAuth Implementation without using Access Gateway 


Develop a resource 
server (web application 
or REST service). 


Register the Resource Server in Access Manager 


Develop a client 
application. 


Register the Client Application in Access Manager 


Configure the client ID 
and secret in the 
application. 


Deploy the resource Deploy the client 
server. application. 
eee Access Manager Interface 


Outside scope of Access Manager 


1. Develop a resource server (web application or REST service). (Application Developer) 


2. Identify scopes and permissions for this resource server. (Application Developer or 
Administrator) 


3. Add the resource server in Access Manager. See “Adding a Resource Server” on page 599. 
(Application Developer or Administrator) 


4. Define the identified scopes and permissions for the resource server in Access Manager. See 
“Defining Scopes and Claims for a Resource Server” on page 600. (Application Developer or 
Administrator) 


5. Develop a client application. (Application Developer) 


6. Register the client application in Access Manager. You can register a client by using 
Administration Console (Administrator), Identity Server (Application Developer or Administrator), 
or REST API (Application Developer or Administrator). See “Registering OAuth Client 
Applications” on page 602 and “Registering a Client Application by Using REST API” on 
page 610. 


7. Identity Server assigns a unique client ID and client secret to this client application. 
8. Configure the client ID and secret in the application. (Application Developer or Administrator) 
9. Deploy the resource server. (Application Developer) 

10. Deploy the client application. (Application Developer) 


For information about basic scenarios in which you can implement this configuration, see “OAuth 
Scenarios” on page 587. 
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For more information about how to enable and configure OAuth in Access Manager for this 
implementation flow, see “Managing OAuth and OpenID Connect” on page 595. 


OAuth Implementation using Access Gateway 


Legacy/New (1) 
REST Service 
Basic Authentication or 
No Authentication 


Create a Reverse Proxy in Access Gateway 


Create OAuth based Authorization Policy (Optionally) 


Create ID Injection Policy 


Create Optional ID Injection Policies to inject other user claims 


Apply Configuration 


ey Access Manager Administration Console 


1. Determine the web application or REST service for which you want to implement this 
configuration. 
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2. Create a reverse proxy in Access Gateway and enable OAuth in Access Gateway for this 
reverse proxy. See “Enabling OAuth in Access Gateway” on page 605. 


3. Configure an authorization policy based on OAuth Scopes. See “Configuring an Authorization 
Policy based on OAuth Scopes’ on page 605. 


4. Configure an Identity Injection policy to inject user name and password. See “Configuring an 
Identity Injection Policy for OAuth Claims” on page 606. 


5. Configure optional Identity Injection policies to inject other user claims, if required. You can 
define the additional roles in the same policy also that you configured for injecting user name 
and password. See “Configuring an Identity Injection Policy for OAuth Claims” on page 606. 


6. Apply the changes. 


For information about the scenario in which you can implement this configuration, see “Legacy Web 
Applications Security” on page 589. 


For information about how to configure OAuth in Access Manager for this implementation flow, see 
“Configuring Access Gateway for OAuth” on page 604. 


OAuth Authorization Grant 


Authorization grant is an intermediate credential that represents the resource owner authorization. To 
request an Access token, the client application obtains authorization from the resource owner. The 
resource owner communicates the authorization in the form of an authorization grant that a client 
application uses to request the Access token. OAuth defines four grant types: authorization code, 
implicit, resource owner credentials, and client credentials. It also provides an extension mechanism 
for defining additional grant types. This section discusses the authorization flow for the following 
grants: 


¢ “Authorization Code Grant (Web Server)” on page 592 
+ “Implicit Grant” on page 593 
e “Resource Owner Credential Grant” on page 594 


¢ “Client Credential Grant” on page 594 


Authorization Code Grant (Web Server) 


Client applications hosted on a secure server use Authorization Code Grant. Client applications use 
this grant to obtain both Access tokens and Refresh tokens. This grant ensures that both types of 
tokens remain with the client web application (the server side) and the authorization server does not 
send these to the browser. Only the authorization code is visible to the browser. 


The client application redirects the resource owner to the authorization server through the web 
browser. The resource owner authenticates at the authorization server. The authorization server 
obtains resource owner's consent and then redirects the web browser with the authorization code to 
the client application. 
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This flow is suitable for client applications who can interact with the resource owner's user-agent and 
can receive incoming requests from the authorization server. 


Identity Server Resource Server 
Authorization Server 


a a 


Client 


Ts 


J 
I9 


Resource Owner 
User 


n 


Redirect... 


..With client_id, scope, state, redirect_uri 


2 
3 Authenticate | | 
A If credentials are valid, redirect... | | 


O ...with authorization code, state to redirect_uri 


Authenticate, request access token with 
authorization code, redirect_uri 


If authorization code is valid, 
return access token 


Request resource with access token 


If access token is valid, supplies | | 


protected resource 


Implicit Grant 


This flow is suitable for client applications residing in the user's device. A client application can 
implement this flow in a browser using a scripting language such as JavaScript or Flash, from a 
mobile device, or from a desktop application. After a user grants the requested authorization, the 
authorization server returns an Access token to the application. An intermediate authorization code is 
not required. As the authorization server sends the Access token to the web browser, this flow offers 
less security than the authorization code. 


Identity Server Web-Hosted Resource Server 


Authorization Server Client resource 


Resource Owner 
User 


= 


Redirect... 


2 ..With client_id, scope, state, redirect_uri 


Authenticate resource owner and 


Ə confirm authorization grant 


Redirect with redirect_uri, access | 


8 token in URI fragment 
O ...to request redirect_uri without the fragment 


Return web page with embedded script to 
extract access token 


@ Execute script to retrieve access token 
O Return access token 
O Request resource with access token 
If access token is valid return 
10 protected resource 
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Resource Owner Credential Grant 


This flow is suitable for client applications who have a trust relationship with resource owners.In this 
flow, the client application sends user's credentials along with its own credentials to the authorization 
server (Identity Server). Identity Server provides an Access token and an Refresh token to the client 
application. The user does not need to log in to approve the request. 


Resource Owner Client Identity Server Resource Server 
User Authorization Server 


a 


wa 


If access token is valid, return 
protected resource 


Client Credential Grant 


The Client Credential Grant is useful for applications that access their own resources from the 
resource server. This grant type only requires the client application’s credentials. Resource owner's 
credentials are not required. 


Client Resource Server 


Resource Owner 


Identity Server 
Authorization Server 


n 


Authenticate, request access token from token endpoint 


OpenID Connect Authentication Flows 


This section describes the flow of OpenID Connect authentication by using the Authorization Code 
flow and Implicit flow. 


¢ “Authentication by Using the Authorization Code Flow” on page 595 
e “Authentication by Using the Implicit Flow” on page 595 
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Authentication by Using the Authorization Code Flow 


In this authentication process, the Token endpoint returns all tokens. The Authorization Code Flow 
returns an authorization code to the client application. The client application exchanges it for an ID 
token and an Access token. The authorization server can also authenticate the client application 
before exchanging the authorization code for an Access token. This process does not expose tokens 
to the User Agent. 


Process Flow: 
1. The client application prepares an authentication request containing the desired request 
parameters and sends the request to the authorization server. 
2. The authorization server authenticates the user. 
3. The authorization server obtains the user consent for the request. 


4. The authorization server sends the user consent to the client application with an authorization 
code. 


5. The client application requests a response by using the authorization code at the Token 
endpoint. 


6. The client application receives a response that contains an ID token and Access token in the 
response body. 


7. The client application validates the ID token and retrieves the user's subject identifier. 


Authentication by Using the Implicit Flow 


In this authentication process, the authorization endpoint returns all tokens. The endpoint returns the 
Access token and ID token directly to the client application that may result in revealing the tokens to 
the user and applications that have access to the User Agent. 


Process Flow: 
1. The client application generates an authentication request containing the desired request 
parameters and sends the request to the authorization server. 
2. The authorization server authenticates the user. 
3. The authorization server obtains the user consent. 


4. The authorization server sends the user to the client application with an ID token and, if 
requested, an Access token. 


5. The client application validates the ID token and retrieves the user's Subject Identifier. 


Managing OAuth and OpenID Connect 


NOTE: NTS will support the Access Manager setup and any app issues where the API request is 
sent to the right Access Manager endpoint. Any other code changes needed to integrate with Access 
Manager are outside the scope of traditional NTS support and need to go through the 
namsdk@netiq.com channel. 


The following is the sequence of the OAuth and OpenID Connect configuration: 


1. Enable the OAuth protocol in Administration Console 
2. Define the global settings 


3. Configure a resource server 
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4. Configure scopes and claims for a resource server 
5. Register client applications 


NOTE: Use Internet Explorer 10 or later, Firefox, or Chrome for configuring OAuth 2.0. 


This section discusses the following topics: 


¢ “Extending a User Store for OAuth 2.0 Authorization Grant Information” on page 596 
+ “Enabling OAuth and OpenID Connect” on page 597 

+ “Defining Global Settings” on page 598 

¢ “Configuring a Resource Server” on page 599 

e “Modifying Scopes of a Resource Server” on page 601 

¢ “Modifying Claims and Attributes” on page 602 

¢ “Managing OAuth Client Applications” on page 602 


Extending a User Store for OAuth 2.0 Authorization Grant Information 


Access Manager OAuth 2.0 implementation stores the information about a client application, which a 
user authorizes to access attributes and resources. This information is unique per user. So, you need 
to store as part of a User Object in the user store. If you already have an attribute, you can use it in 
Authorization Grant LDAP Attribute while defining Global Settings. 


If a free attribute is unavailable, then extend the User Object schema to add a new single-valued 
binary (LDAP) stream (eDirectory) attribute with a name. Access Manager will store an XML object in 
this attribute for each user authorization. 


The following example describes how to extend the schema of a User Object in eDirectory: 


Click to Roles and Tasks > Schema > Create Attribute. 
Specify Attribute Name as nidsOAuthGrant. 

Click Next. 

Select Stream under Syntax. 

Click Next. 

Select Single Valued. 

Click Next > Finish. 

Go to Roles and Tasks > Schema > Add Attribute. 
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Select Person under Available Classes. 

Click OK. 

Move nidsOAuthGrant from Available optional attributes to Optional attributes. 
Click OK. 


RRG 
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Enabling OAuth and OpenID Connect 


Access Manager ships with only SAML 1.1, Liberty, and SAML 2.0 enabled by default. To use OAuth, 
you must enable it in Identity Server. Otherwise, the configuration will not work. 


To enable OAuth and OpenID Connect, perform the following steps: 
1 Click Devices > Identity Servers > Edit. 
2 Inthe Enabled Protocols section, select OAuth & OpenID Connect. 


3 Click OK. 
4 Update Identity Server. 


NOTE: For OAuth authorization, Identity provider and ESP must be enabled with SSL. 
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Defining Global Settings 


The Global Settings page enables you to specify the default OAuth and OpenID Connect settings for 
the authorization server such as issuer URL, token types, grants, and so on. 


1 Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Global Settings. 
2 You can configure and view the following details on this page: 


Field Description 
Issuer Specify the name of the authorization server. This name is part of the ID 
token. 


Authorization Grant LDAP Specify a valid LDAP attribute. The attribute specified must exist in the 
Attribute user store. 


Ascope uses this attribute to store user consent. Whenever a user grants 
authorization to an application, this attribute is updated. Ensure that no 
other application uses this attribute. 


For more information, see “Extending a User Store for OAuth 2.0 
Authorization Grant Information” on page 596. 


CORS Domains Select any one of the following options based on your requirement: 


+ None: If you want to deny access for requests from all domains other 
than the domain of the resource. The resource referred here are 
resources such as Javascript on the client application. 


+ Allow All: If you want to allow access for requests from any 
domains. 


+ Limit to: If you want to allow access for requests from only selected 
domains. Specify the domain. 


Examples: beem://www.test.com, fb://app.local.url, https:/ 
/namapp.com 


Grant Type(s) Select the types of grants that the authorization server will support. Based 
on the grant type you select, the system selects corresponding token type 
by default. 


For more information about grant types, see “OAuth Authorization Grant” 
on page 592. 


Token Type(s) Select the types of tokens that the authorization server will support. 


+ ID Token: A security token that contains claims about the 
authentication of an end user by an authorization server to the 
relying party. 


+ Access Token: Includes the specific scopes and durations of 
granted access. 


+ Refresh Token: Used to obtain a new access token when an Access 
token becomes invalid or expires. 


Authorization Code Timeout Specify the duration in minute after how long the authorization code 
becomes invalid. 


Access Token and ID Token Specify the duration in minute after how long the Access token and ID 


Timeout token become invalid. 
Refresh Token Timeout Specify the duration in minute after how long the Refresh token becomes 
invalid. 
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Field Description 


Supports Signing Select this option if you want the authorization server to sign the ID token 
If you selected Supports Signing, select a signing certificate. 
Signing Certificate Select a certificate to sign ID tokens. 


If you are using Access Manager 4.3 Service Pack 3, you can add the 
external OAuth signing certificates in the certificate list by adding the 
certificate in the Signing keystore of the Identity Server. 


Contracts for Resource Select the supported contracts from the Available contracts list and 
Owner Credentials move them to the Contracts Field. 
Authentication 


This option allows the administrator to configure the Resource Owner flow 
to execute specific authentication contract. It supports Name/Password 
based contracts only. 


The order of authentication contract execution must be as follows: 
1. The acr_values in request parameter. 
2. OAuth Global Setting option. 


3. Default contract. 


For example, If no acr_values and no global RO authentication 
contracts are specified, then only the default authentication contract of 
Identity server is executed. 


To select a custom contract for authentication, the custom authentication 
class must override the cbAuthenticate method. For more information, 
see the NetiQ Access Manager 4.3 Developer Guide. 


3 Click OK. 


Configuring a Resource Server 


Access Manager allows you to define settings for each resource server. A resource server validates 
and accepts tokens sent by client applications, and then grants access to resources. 


Setting up a resource server includes adding a resource server, defining scopes, and defining claims 
associated with each scope. Scopes and claims decide what resources client applications can 
access and what actions they can perform on the resources. 


Access Manager also allows you to modify and delete configured resource servers. Configuring a 
resource server consists of the following actions: 


+e “Adding a Resource Server” on page 599 
¢ “Defining Scopes and Claims for a Resource Server” on page 600 
¢ “Restricting the Number of Requests” on page 601 


Adding a Resource Server 
Perform the following steps: 


1 Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server. 
2 Click New. 
3 Specify a name for the resource server. 
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4 Click OK. 
Continue with “Defining Scopes and Claims for a Resource Server” on page 600. 


Defining Scopes and Claims for a Resource Server 


A scope is a set of permissible actions that a client application can perform on the accessed 
resources. You can define scopes and then set up claims or permissions for each scope. When a 
user grants client applications access to protected resources, they can perform actions based on 
permissions defined in the scope. 


A scope can be of the following two types: 


+ Resource permissions: The resource server can fetch these scopes/permissions specific to 
requirements. For example, for the edit_photo scope, the resource server recognizes and grants 
edit rights for the photo. 


+ User Claims: Access Manager acts as a special resource server managing access to users' 
claims. A client application can request these claims. 


For example, you can define a scope named email and define permissions associated with this scope 
such as read only. A client application who will access the email can only read the content. 


NOTE: 


+ You can get only LDAP based attributes in a scope. 


+ You can configure roles as OAuth scope and use them to inject with the Identity Injection policy. 
Role attribute is calculated when the token is sent to user info endpoint. 


Perform the following steps to define scopes and permissions: 


1 Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server. 
2 Select the resource server name for which you want to define a new scope. 

3 Click New. 

4 Specify the following details: 


Field Description 
Name Specify a name for the scope. 
Description Specify a description for the scope. The consent page shows 


this description. 


Require user permission Select this option if this scope requires the user’s permission 
before providing access to the protected resources. 


Contains user's claims Select this option to include user's claims in this scope. 


Allow modification in consent Select this option to allow modification in consent. When 
selected, the resource owner can choose not to share this scope 
with the client application. 


5 Click Next. 
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6 Based on whether you have selected Require user permission, you need to perform any one of 
the following actions: 


+ Select an attribute set: If you have selected the Require user permission option, Identity 
Server will fetch the required information from the user endpoint. You must specify the 
LDAP attributes. You can select an attribute set from the list or create a new attribute set. 
For more information about how to create an attribute set, see Section 3.5.1, “Configuring 
Attribute Sets,” on page 80. 


+ Create Claims/Permissions: If you have not selected Require user permission, create 
claims for the scope. 


¢ Click New, specify a name for the claim, and click OK. 
7 Click Finish. 
Restricting the Number of Requests 
You can restrict the number of users accessing a service by updating the tomcat . conf file. 
Linux: 
Open /opt/novell/nam/idp/conf/tomcat .conf. Add the following parameter: 


JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.oauth.threshold.maxrequestsallowed=<number of 
requests>" 


For example, JAVA_OPTS="${JAVA_OPTS} - 
Dcom.novell.oauth.threshold.maxrequestsallowed=10". It will not allow more than 10 request 
per second. 


Windows: 


. Go to C:\Program Files (x86)\Novell\Tomcat\bin. 
. Open Tomcat7w. 
. Navigate to the Java tab. 


kW N > 


. Add the following option: 


JAVA_OPTS="${JAVA_OPTS} - 
Dcom.novell.oauth.threshold.maxrequestsallowed=<number of requests>" 


5. Click Apply and restart Identity Server. 


Modifying Scopes of a Resource Server 


You can modify the scopes of a registered resource server. Access Manager allows you to delete a 
resource server or delete the scope of a resource server. 


To modify scopes of a resource server, perform the following steps: 
1 Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server. This 
page lists all registered resource servers. 
2 Click the resource server > scope you want to modify. 


3 On the Edit Scope page, modify the details as required. For more information about the fields on 
this page, see “Defining Scopes and Claims for a Resource Server” on page 600. 


4 Click OK. 
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Modifying Claims and Attributes 


You can modify or delete a defined claim. You can also update the attributes associated with a scope. 
If you have selected Require user permission while creating the scope, Identity Server fetches the 
required information from the user endpoint. In this case, you can change the associated LDAP 
attributes. 


If you have not selected Require user permission, the scope contains claims instead of LDAP 
attributes. You can change the name of the claim. For more information about the fields on this page, 
see “Defining Scopes and Claims for a Resource Server” on page 600. 


Managing OAuth Client Applications 


A client application that sends API requests to the authorization server must be registered with the 
authorization server. As part of the registration, specify the client name, redirections (URIs), and any 
other provider-specific data required by the API. You can register a client application in Administration 
Console or in Identity Server. 


Prerequisites for managing client applications include: 


+ Administration Console: The user must have the NAM_OAUTH2_ADMIN role defined in the 
OAuth policy. 


¢ Identity Server: The user must have the NAM_OAUTH2_DEVELOPER role defined in the OAuth 
policy. 


An application developer must log into Identity Server for registering a client application. 


The My Applications tab lists all the applications that you added. You can view details, modify, and 
delete applications. 


Registering OAuth Client Applications 
Perform the following steps to register a client application: 


1 Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Client Applications > 
Register New Clients. 


2 Specify the following details: 


Field Description 
Client Name Specify the name of the client application. 
Client Type Select whether this is a web-based or a desktop 


client application. 
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Field Description 


Redirect URIs Specify the URI based on the Client type. 


Specify the URIs that Identity Server uses to send 
the authorization code and implicit requests. 


For web-based applications specify the client type 
in this format: https://client.example.org/callback 


For native/desktop applications, specify the client 
type in any one of the following formats: 


https: //www.namnetiq.in/ 
x-com.netiq.sample://www.namnetiq. in/ 
urn:ietf:wg:oauth:2.0:oob 


Grants Required Select the grant types required for this client 
application. Available grant types include: 


+ Authorization Code (default) 
+ Implicit 
+ Resource Owner Credentials 


+ Client Credentials 


Token Types Select the token type that the authorization server 
will return to this client application. The following are 
available tokens: 


+ Code 
+ ID Token 
Refresh Token 


+ 


+ 


Access Token 


3 Click Consent Screen Configuration. 


Specify the following details: 


Field Description 

Client Logo URL Specify the URL of the logo that you want to include in the consent 
page. 

Privacy Policy URL Specify the URL of the privacy policy you want to include in the 
consent page. You can define your own privacy policy. 

Terms of Service URL Specify the URL of the terms of service. 

Contacts Specify email addresses of people related to this client application. 


4 Click Authorized JavaScript origins (CORS) and add Domains. The domains configured here 
can access restricted resources available on the client application. This is an optional step. 


Examples: beem://www.test.com, fb://app.local.url, https://namapp.com 
5 Click Advanced OpenID Connect. This is an optional step. Specify the following details: 
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Field Description 


JSON Web Key Set URI Specify the URI of the JSON file containing the 
JSON web keys. 

ID Token Signed Response Algorithm Specify the ID Token Signed Response Algorithm. 

ID Token Encrypted Response Algorithm Specify the algorithm used to encrypt the key. 

ID Token Encrypted Response Enc Specify the algorithm used to encrypt the content. 


6 Click Register Client. 


Identity Server assigns a client ID and a client secret. To see this ID and secret, go to the list of 
registered client applications on the Client Application page and click the view icon for this client 
application. 


Modifying Registered Client Applications 
To modify a registered client application, perform the following steps: 


1 Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Client Applications. The 
page lists all registered client applications along with the following details: 


Field Description 

Client Application Name of the registered application 

Application Type Type of the application: Web or Native/Desktop 

Created By User name of the person who has registered the client application. 
Actions List of icons associated with actions that you can perform on an 


application. You can perform the following actions: 
+ View details of a registered client application 
+ Delete a registered client application 


+ Modify details of a registered client application. 


2 Click the edit icon under Actions. The Client Configuration page opens. Modify the details as 
required. For more information about fields, see “Registering OAuth Client Applications” on 
page 602. 


3 Click Modify Client. 


5.2.10.10 Configuring Access Gateway for OAuth 
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You can configure Access Gateway to validate OAuth tokens on behalf of the resource server. If the 
token is not valid then Access Gateway returns the unauthorized 401 error to the client application. 
You can also configure Access Gateway to inject OAuth tokens on behalf of the web applications. 


Configuring Access Gateway for OAuth consists of the following: 


1. Enabling OAuth in Access Gateway 
2. Configuring an Authorization Policy based on OAuth Scopes 
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3. Configuring an Identity Injection Policy for OAuth Claims or Configuring an Identity Injection 
Policy for User Passwords 


4. Configuring Access Gateway to Inject OAuth Tokens 


Enabling OAuth in Access Gateway 


If you want Access Gateway to validate a token before granting access to a protected resource, you 
must enable OAuth for that protected resource. 


Perform the following steps to enable OAuth in Access Gateway: 


1 Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name]. 
2 Select the Protected Resources tab. 

3 Click the protected resource for which you want to enable OAuth. 

4 Select Validate OAuth Token. 

5 Click OK. 


Configuring an Authorization Policy based on OAuth Scopes 


You must configure an authorization policy and then assign it to the protected resource. Access 
Gateway makes decisions based on the rules defined in the authorization policy after validating the 
OAuth tokens. 


Resources protected by OAuth tokens do not execute any authentication procedure. Hence, 
evaluation of policies associated with OAuth protected resources cannot fetch any user attributes 
outside the OAuth scope. All the user attributes needed for the protected resource must be part of the 
OAuth scope. Ensure that the proxy services protected by OAuth are not associated with any policies 
that refer to authentication contract, profiles, LDAP attribute, LDAP OU, roles, or RISK score. Any 
policy, which requests for data other than the scope of OAuth token fails. 


Perform the following steps to configure an Authorization policy for scopes: 


Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name]. 
Select the Protected Resources tab. 

Click the protected resource for which you want to configure an Authorization policy. 

Select the Authorization tab. 

Click Manage Policies > New. 

Specify a name for the policy and select Access Gateway: Authorization for the policy type. 
Click OK. 

Specify the following details: 


On Oo FF WY FP 


Field Action 


Description (Optional) Describe the purpose of this rule. 


Priority Specify the order in which a rule is applied in the policy, when the policy has multiple 
rules. The highest priority is 1 and the lowest priority is 10. 


NOTE: If two rules have the same priority, a Deny rule is applied before a Permit 
rule. 


Conditions Click New and then select OAuth Scopes. 


For Value, select the scope from the list. 
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Field Action 


Actions Select one of the following: 
+ Permit: Allows the user to access the resource. 
+ Deny: Select one of the following deny actions: 


+ Display Default Deny Page: Displays a generic message, indicating that 
the user has insufficient rights to access the resource. 


+ Deny Message: Allows you to provide a customized message that you 
want to display to users after denying their access attempts. 


+ Redirect to URL: Allows you to specify a URL to redirect users after 
denying access. For example: http://www. example.com 


¢ Redirect: Specify the URL to which you want the users to redirect when they 
meet the conditions of this policy. 


+ Re-authenticate with Contract: Allows you to specify an authentication 
contract used to authenticate the user. 


9 Click OK > OK. 
10 Select the policy you created and click Apply Changes > Close. 
The Authorization page of the protected resource opens. 
11 Select the Authorization policy and click Enable > OK. 


Configuring an Identity Injection Policy for OAuth Claims 


You must configure an Identity Injection policy if you want to send the claims details to the resource 
server. Claims can include user attributes or permissions. 


Perform the following steps to configure an Identity Injection policy for scopes: 


Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name]. 
Select the Protected Resources tab. 

Click the protected resource for which you want to configure an Identity Injection policy. 
Select the Identity Injection tab. 


Click Manage Policies > New. 
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Specify a name for the policy, and then select Access Gateway: Identity Injection for the type of 
policy. 

7 Click OK. 

8 Specify the following details: 
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Field Action 
Description Specify the purpose of this policy. 


Priority Specify the sequence in which you want to apply the rule in the policy, if the policy 
has multiple rules. The highest priority is 1 and the lowest priority is 10. 
Action Click New, then select one of the following: 


+ Inject into Authentication Header: Inserts the user name and password 
into the header. Select OAuth Claims under user name and then select a 
claim. 


+ Inject into Custom Header: Inserts custom names into the custom header. 
Select OAuth Claims under Value and then select a claim. 


+ Inject into Custom Header with Tags: Inserts custom tags with name/value 
content into the custom header. Select OAuth Claims under Tag Value and 
then select a claim. 


+ Inject into Query String: Inserts a query string into the URL for the page. 
Select OAuth Claims under Tag Value and then select a claim. 


+ Inject Kerberos Ticket: Inserts authentication values from the Kerberos 
ticket into the custom header. Select OAuth Claims under Value and then 
select a claim. 


9 Click OK > OK. 
10 Select the policy you created and click Apply Changes > Close. 
11 The Identity Injection page of the protected resource opens. 
12 Select the Identity Injection policy and click Enable > OK. 


Configuring an Identity Injection Policy for User Passwords 


Ensure that you have enabled the Allow admin to retrieve passwords option under Universal 
Password Retrieval in the eDirectory user store for all users, so that the policy can retrieve the 
password from the user store. Without this configuration, the identity injection policy for user 
password will not work. 


For more information about how to enable the password retrieval in eDirectory, see Universal 
Password Configuration Options in the Password Management Administration Guide. 


NOTE: The password retrieval works only with eDirectory. 


Perform the following steps: 


Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name]. 
Select the Protected Resources tab. 

Click the protected resource for which you want to configure an Identity Injection policy. 

Select the Identity Injection tab. 

Click Manage Policies > New. 

Specify a name for the policy and select Access Gateway: Identity Injection for the policy type. 
Click OK. 
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8 Configure the policy with the following details: 
+ Action: Select Inject into Authentication Header. 
+ User name: Select OAuth Claims > Access Token: User 
+ Password: Select OAuth Claims > Password 
9 Click OK > OK. 
10 Select the policy you created and click Apply Changes > Close. 
The Identity Injection page of the protected resource opens. 
11 Select the Identity Injection policy and click Enable > OK. 


Configuring Access Gateway to Inject OAuth Tokens 


To configure Access Gateway to inject OAuth tokens, see Section 8.4.9, “Configuring an OAuth 
Token Inject Policy,” on page 828. 


5.2.10.11 Viewing Endpoint Details 


In Administration Console Dashboard under Devices > Identity Servers > Edit > OAuth & OpenID 
Connect > EndPoint Summary, you can view the following endpoints: 


¢ Authorization EndPoint: Enables client applications to interact with the resource owner and 
obtain an authorization grant. It is located on an authorization server. 


¢ Registration EndPoint: Enables registering client applications on the authorization server. It is 
located on the authorization server. 


¢ Token EndPoint: Enables client applications to obtain an Access token by providing its 
authorization grant or Refresh token. It is located on an authorization server. 


+ Userinfo EndPoint: Provides information about the user associated with the Access token in 
the standard OpenID Connect format. 


+ OpenID Metadata EndPoint: Provides information about OpenID provider metadata. 


NOTE: As per OAuth specifications, endpoints must not accept any non-HTTPS request. However, 
Access Manager supports non-HTTPS requests also. This is required to enable OAuth in scenarios 
when Access Manager is deployed behind a third-party SSL accelerator. 


5.2.10.12 OAuth and OpenID Connect Audit Events 


Access Manager provides the following OAuth audit events: 


+ OAuth & OpenID Token Issued 

+ OAuth & OpenID Token Issue Failed 

+ OAuth Consent Provided 

+ OAuth Consent Revoked 

+ OAuth Client Applications 

+ OAuth & OpenID Token Validation Success 
+ OAuth & OpenID Token Validation Failed 


For more information, see Section 19.2, “Enabling Identity Server Audit Events,” on page 1021. 
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5.2.10.13 Enabling Logging for OAuth and OpenID Connect 
To enable logging for OAuth and OpenID Connect events, perform the following steps: 


1 Click Devices > Identity Servers > Edit > Auditing and Logging. 
2 Select Enabled under File Logging. 


3 In the Component File Logger Levels section, specify any one of the following options for OAuth 
and OpenlD Connect: 


¢ Off: Turns off component file logging 

+ Severe: Logs serious failures that can stop system processing 

+ Warning: Logs potential failures that have minimal impact on execution. 
¢ Info: Logs informational events. 

¢ Verbose: Logs static configuration information 


The system logs any configuration errors under one of the primary three levels: Severe, 
Warning, and Info. 


+ Debug: Logs events for all of the preceding levels (Severe, Warning, Info, and Verbose) 


4 Click OK. 


5.2.10.14 Managing Clients Applications by Using REST API 
You can programmatically register, view, modify, and delete a client application in Access Manager. 


Before performing any of these actions, you must have your role defined as NAM_OAUTH2_DEVELOPER 
or NAM_OAUTH2_ADMIN in the OAuth policy. 


You can register an application in any of the following two ways: 


+ Using username and password 


+ Using Access token: To register a client application by using an Access token, you must have 
your role defined as NAM_OAUTH2_DEVELOPER in the OAuth policy. 


Use the Resource Owner flow to get an Access token. The endpoint for Resource Owner flow is 


https://</dentity Server URL: Port Number>/nidp/oauth/nam/token. This endpoint requires the 
followings parameters to provide an Access token: 


Parameter Value 

grant_type password 

username Application developer’s user name 

password Application developer's password 

scope + urn:netiq.com:nam:scope:oauth:registration:full (This 


scope allows you to register, view, modify, and delete client 
applications.) 


+ urn:netiq.com:nam:scope:oauth:registration:read (This 
scope provides read-only access) 


token endpoint Identity Server URL: Port Number>/ nidp/oauth/nam/token 
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This section discusses the following topics: 


e “Registering a Client Application by Using REST API” on page 610 
e “Modifying a Client Application by Using REST API” on page 611 

¢ “Viewing a Client Application by Using REST API” on page 612 

¢ “Deleting a Client Application by Using REST API” on page 612 


Registering a Client Application by Using REST API 

To register a client application, the HTTP method value must be POST. 

Identity Server uses the following endpoint for registering a client application: 
https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients 


The endpoint requires the following parameters: 


Table 5-5 OAuth Parameters for Client Registration 


Parameter Value Required/Optional 
client_id Name of the client application. Required 
application_type web or native Optional 
response_types Redirection URI values used by the client Required 
application. 
grant_types The following are the supported grant Optional 
types: 


+ authorization_code 

¢ implicit 

¢ refresh_token 

+ resource_owner_credentials 


¢ client_credentials 


If you do not specify a grant type, the 
default grant type is used. The default 
value is authorization_code. 


response_types The following are the supported response Optional 
type: 


+ code 
+ id_token 


+ access_token 


logo_uri Specify the URL of the logo that you want Optional 
to include in the consent page. 


Example: https://client.example.org/ 
logo.png 
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Parameter 


policy_uri 


tos_uri 


contacts 


jwks_uri 


id_token_signed_response_alg 


id_token_encrypted_response_alg 


id_token_encrypted_response_enc 


Value 


URL of the Relying Party Client’s privacy 
policy. 


Example: https://client.example.org/ 
privacypolicy 


URL of the Relying Party's terms of 
service 


Example: https://client.example.org/terms 


Email addresses of people related to this 
client application. 


Specify the URI of the JSON file 
containing the json web keys. This key set 
contains signing keys that the relying 
party uses to validate signatures from the 
OpenID provider. 


Example: https://client.example.org/ 
my_public_keys.jwks 


Specify the ID Token Signed Response 
Algorithm. This algorithm is required for 
signing the ID token issued to the client. 


Specify the algorithm used to encrypt the 
key. 


Specify the algorithm used to encrypt the 
content. 


Modifying a Client Application by Using REST API 


Perform the following steps: 


1 Retrieve the client details from the https://<Identity Server URL: Port Number>/nidp/ 


Required/Optional 


Optional 


Optional 


Optional 


Optional 


Optional 


Optional 


Optional 


oauth/nam/clients/<client ID> endpoint. In the request for retrieving client details, use GET 


as the HTTP method value. 


2 Send the update request. In the update request, use POST as the HTTP method value. 


Identity Server uses the following endpoint for modifying a registered client application: 
https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/ 


For the list of parameters this endpoint requires for a client application modification, see Table 5- 


5 on page 610. 


NOTE: For updating a client application, you must send the complete xml with all parameters during 
the update request. If you do not include a parameter in the update xml, the server will not initialize 

this parameter. For example, if you want to update the response_types parameter, send the updated 
value for this parameter and existing values for other parameters in the request. 
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Viewing a Client Application by Using REST API 
To view a client application, use GET as the HTTP method value. 
You can view a registered client application by using the following two endpoints: 


+ https://<Identity Server URL: Port Number>/nidp/oauth/namiIclients/: To view all clients 
applications registered by a developer 


+ https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/<client ID>: To view a 
specific client application registered by a developer 


Deleting a Client Application by Using REST API 
To delete a client application, the HTTP method value must be DELETE. 
Identity Server uses the following endpoint for deleting a registered client application: 


https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/<client ID> 


5.2.10.15 Managing OAuth 2.0 Resource Server and Scope by Using REST API 


You can programmatically register, view, modify, and delete a resource server and scopes in Access 
Manager. 


¢ “Registering a Resource Server by Using REST API” on page 612 
¢ “Deleting a Resource Server by Using REST API” on page 613 

e “Viewing Registered Resource Servers” on page 613 

e “Creating a Scope by Using REST API” on page 613 

e “Modifying a Scope by Using REST API” on page 614 

¢ “Deleting a Scope by Using REST API” on page 614 

e “Viewing Configured Scopes by Using REST API” on page 614 


Registering a Resource Server by Using REST API 


To register a resource server by using REST API, you must have your role defined as 
NAM_OAUTH2_ADMIN in the OAuth policy. Send an HTTPS POST request with the appropriate URI 
parameters to resource server endpoint URI. The request includes the following information:Scope: 
urn:netig.com:nam:scope:oauth: registration: full 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers 


HTTP Method: POST 


URI Parameter: Include the following parameter: 


Parameter Required Description 


name yes Name of the resource server 
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Deleting a Resource Server by Using REST API 


To delete a resource server by using REST API, you must have your role defined as 
NAM_OAUTH2_ADMIN in the OAuth policy. The delete request includes the following details: 


Scope: urn:netig.com:nam:scope:oauth:registration: full 
HTTP Method: DELETE 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers/<resourceServerName> 


Viewing Registered Resource Servers 


To view all registered resource servers by using REST API, you must have your role defined as 
NAM_OAUTH2_ADMIN or NAM_OAUTH2_DEVELOPER in the OAuth policy. The request includes the 
following details: 


Scope: urn:netigq.com:nam: scope: oauth:registration: full 
HTTP Method: GET 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers 


Creating a Scope by Using REST API 


To create a scope by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN in the 
OAuth policy. The request includes the following details: 


Scope: urn:netigq.com:nam: scope: oauth:registration: full 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers/<resourceServerName>/scopes 


HTTP Method: POST 


Request URI Parameters: 


Parameter Required Description 
scope Yes Name of the scope 
scope_description Yes Description of the scope. The 


consent page displays this 
description while obtaining 
authorization from the user. 


claims Either claims or attribute_set is List of claims 


required. 
attribute_set Attribute name and attribute dn. 


Sample: { "name" : "jpeg_photo", 
"dn" : "cn=jpeg_photo,o=novell"} 


userPermissionRequired No Boolean value. Default value is 
true. 
adminApprovalRequired Yes Boolean value. Default value is 


true, set it to false always. 
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Parameter Required Description 


isGroupOfUserAttributes No Boolean value. Default value is 
false. 

allowModifyInConsent No Boolean value. Default value is 
false. 


Modifying a Scope by Using REST API 


To modify a scope by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN in the 
OAuth policy. The request includes the following details: 


Scope: urn:netigq.com:nam:scope:oauth:registration: full 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers/<resourceServerName>/scopes/<scopename> 


HTTP Method: POST 


Send only those parameters which you want to modify. 


Deleting a Scope by Using REST API 


To delete a scope by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN in the 
OAuth policy. The request includes the following details: 


Scope: urn:netigq.com:nam:scope:oauth: registration: full 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers/<resourceServerName>/scopes/<scopename> 


HTTP Method: DELETE 


Viewing Configured Scopes by Using REST API 


You can view details of all scopes together or a specific scope. To view a scope by using REST API, 
you must have your role defined as NAM_OAUTH2_DEVELOPER or NAM_OAUTH2_ADMIN in the OAuth 


policy. 

Viewing Details of a Specific Scope 

The request includes the following details: 

Scope: urn:netigq.com:nam:scope:oauth:registration: full 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers/<resourceServerName>/scopes/<scopename> 


HTTP Method: GET 


Viewing Details of All Configured Scopes 
The request includes the following details: 
Scope Required: urn:netig.com:nam:scope:oauth: registration: full 


Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/ 
resourceservers/<resourceServerName>/scopes 


HTTP Method: GET 
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5.2.10.16 


5.2.10.17 


End User Operations 


End users can perform the following actions: 


¢ “User Authorization” on page 615 


e “Revoking Authorizations” on page 615 


User Authorization 


When end users access a client application, they are required to give consent for the application to 
access their email, basic profile, and any other information. An administrator configures a list of 
allowed scopes. The Consent page shows only these scopes. For example, if an administrator 
configures email and basic profile, a user can see only these two scopes in the consent page. 


Select the scope that you want the application to access and click Accept. 


NOTE: Email is a mandatory scope configured by the administrator and all client applications can 
access this scope by default. You cannot deselect this scope on the consent page. 


The client application must remember the scopes a user has provided earlier in the consent. For the 
next request, the client application must ask for the scopes that the user did not provide in the earlier 
request. For example, if a client application asks for five scopes and the user provides only three 
scopes, the client application must remember user's choice and must not ask for the five scopes 
again unless it is an absolute requirement. 


Revoking Authorizations 


You can view all authorized client applications with their scopes and claims under the Authorized 
Applications tab. An end user can revoke the consent given earlier to client applications by using the 
Revoke Consent page. 


Log into Identity Server and go to Applications > Authorized Applications. You can view details of 
client applications and revoke the client applications’ access if required. 


Configuring the Demo OAuth Application 


This application demonstrates how to protect an OAuth enabled application by using Access 
Manager. This application contains a RESTful web service and a client application that uses this 
RESTful web service. 


The RESTful web service allows you to perform TODO tasks for a hypothetical application. This web 
service exposes an API to add, modify, and delete tasks on behalf of a user. The client application 
provides a web interface that uses REST APIs to manage these tasks. The REST service protects 
REST APIs with OAuth Access tokens issued by a trusted Access Manager OAuth provider. 


This demo configuration provides a way to test OpenID connect endpoints such as metadata, 
userinfo, and tokeninfo endpoints. 


Download OAuth 2.0 Demo Application and follow the instructions provided in the RunningDemoApp 
document. 
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5.2.11 


5.2.11.1 


Configuring Authentication Through Federation for Specific 
Providers 


+ 


+ 


+ 


+ 


Section 5.2.11.1, “Setting Up Google Applications,” on page 616 
Section 5.2.11.2, “Setting Up Office 365 Services,” on page 617 


Section 5.2.11.3, “Integrating Salesforce With Access Manager By Using SAML 2.0,” on 
page 617 


Section 5.2.11.4, “Integrating Shibboleth Identity Provider With Access Manager,” on page 619 


Setting Up Google Applications 


Google Applications are pre-configured to establish federation with external service providers. 


1 


Click Devices > Identity Servers > Edit > [Protocol]. 
For the protocol, click SAML 2.0. 


Click New > Service Provider. 


NOTE: By default, the Provider Type > General is selected. 


Select Google Application from the Provider Type drop-down list. 


By default, the Metadata Text source is selected and the Text field is pre-filled with the metadata 
XML. You must edit the Location in the metadata text and replace YOURDOMAIN with the 
domain name configured in Google Applications. 


4 Inthe Name option, specify a name by which you want to refer to the provider and click Next. 


5 Review the metadata certificates and click Finish. For Google Applications, the certificates page 


displayed is empty because the metadata does not contain information about the certificates. 
The system displays the trusted provider on the protocol page. For example, if you have 
specified the Name as GoogleApps, the page displays the trusted service provider when you 
click Finish. 


Figure 5-19 Trusted Service Provider for Google Application/Office 365/Sales Force 


y. | Policies 


Identity Servers > 


IDP 


General \ Local \ Liberty \ SAML 1.1 ASUBA WS Federation \ Brokering \ WS-Trust \ 


Trusted Providers | | Profiles 


Newy | Delete | Enable | Disable 

E] Name Enabled Metadata Expiration Date Metadata Repository 
Identity Providers 

No items 


Service Providers 


E| GoogleApps Vv Not specified Not Applicable 
E] Office365 Vv Not specified Not Applicable 
E] SalesForce v Not specified Not Applicable 
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5.2.11.2 


5.2.11.3 


6 Click OK, then update Identity Server. 


The wizard allows you to configure the required options and relies upon the default settings for 
the other federation options. For information about how to configure the default settings and how 
to configure the other available options, see Section Section 3.9.4, “Modifying a Trusted 
Provider,” on page 185. 


You can configure Access Manager to provide the single sign-on services to Google applications by 
using Security Assertion Markup Language (SAML) 2.0. For more information, see Integrating 
Google Apps and Novell Access Manager using SAML 2.0. 


Setting Up Office 365 Services 


Office 365 is pre-configured to establish federation with external service providers. For more 
information, see “Setting Up Google Applications” on page 616. In Step 3 on page 616, select Office 
365. The system displays the trusted provider on the protocol page. For example, if you have 
specified the Name as Office365, the screen displays the trusted service provider Office365 as in 
Figure 5-19 on page 616, when you click Finish. 


Access Manager is compatible with Microsoft Office 365 and provides single sign-on access to Office 
365 services. 


For more information, see Chapter 5.2.13, “Configuring Single Sign-On for Office 365 Services,” on 
page 622. 


Integrating Salesforce With Access Manager By Using SAML 2.0 


Salesforce.com is pre-configured to establish federation with external service providers. 


Integrating Salesforce With Access Manager By Using SAML 2.0 for Identity 
Provider Initiated Login 


To integrate Salesforce for idpsend, follow the procedure in “Setting Up Google Applications” on 
page 616. In Step 3 on page 616, select Salesforce. The system displays the trusted provider on the 
protocol page. For example, if you have specified the Name as SalesForce, the screen displays the 
trusted service provider as in Figure 5-19 on page 616, when you click Finish. 


Access Manager allows your users to use their existing LDAP credentials for single sign-on access to 
salesforce.com as well as any Web applications protected by Access Manager. 


For information using SAML 2.0 for Identity Provider initiated login, follow the procedure below. 


1 Create domain in Salesforce. 


To enable IDP-initiated login in Salesforce.com, you must enable and configure the My Domain 
option in Salesforce.com. Defining your own domain provides the basis for an IDP-initiated URL. 


1a Login as administrator. Go to Administration Setup > Domain Management > My Domain. 
1b Specify the subdomain name and check the availability. 
1c Agree to the terms and conditions and click Register Domain. 
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2 If you have already configured your identity provider for Salesforce.com using the wizard, you 
must update configuration in the identity provider according to the new domain. Perform the 
following steps. 


2a Download the metadata from Salesforce site for your domain. See Step 3 on page 616. 
Send and import this metadata into your Identity Server Salesforce configuration. For 
reimporting metadata in Access Manager Identity Server, see “Viewing and Reimporting a 
Trusted Provider’s Metadata” on page 189. 


2b Change the Intersite Transfer URL to point to the new domain URL 
3 Perform Step 4 on page 619 and Step 5 on page 619. 
4 Update Identity Server. 


Integrating Salesforce With Access Manager By Using SAML 2.0 for Service 
Provider Initiated Login 


Service provider configuration options offer you more flexibility and control for example, 
simultaneously federating with more than one Identity Server. Salesforce.com also supports SP- 
initiated login along with IDP-initiated login. SP-initiated login lets the user use a simple and intuitive 
URL to access the target application. 


Follow the procedure given below to integrate Salesforce with Access Manager by using SAML 2.0 
for service provider initiated login. Assume that the user has a Salesforce account. 
1 Create domain in Salesforce. 


To enable SP-initiated login in Salesforce.com, you must enable and configure the My Domain 
option in Salesforce.com. Defining your own domain provides the basis for an SP- initiated URL. 


1a Login as administrator. Go to Administration Setup > Domain Management > My Domain. 
1b Specify the subdomain name and check the availability. 
1c Agree to the terms and conditions and click Register Domain. 


If you have already configured your identity provider for Salesforce.com using wizard, you 
must update configuration in the identity provider according to the new domain. Perform the 
following steps. 


NOTE: Configure SSO configuration. Follow the procedure below to enable SAML support in 
Salesforce. 


1. Go to your Salesforce account and login. 


2. From the left panel, select Security Control > Single sign setting > Saml Single Sign-on 
Setting > New and fill the form. 


3. To enable SAML select Security Control > Single sign setting > Saml Single Sign-on 
Setting > Federated Single Sign-On Using SAML > Edit > Enable Saml. 


2 Change the Intersite Transfer URL to point to the new domain URL. 
3 Import Salesforce metadata in Access Manager. 
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As with any other SAML federation you must configure both your Access Manager Identity 
Server and Salesforce.com Service Provider (SP) to establish a trust. You now have an option to 
download your metadata from Salesforce.com. To download your specific metadata go to your 
Salesforce.com instance. 


3a Login as administrator. Go to Administration Setup > Security Controls > Single Sign-On 
Settings. 


3b Select Name which you have configured above and Download Metadata. 


3c Reimport this metadata into your service provider configuration in Access Manager 
assuming that you have created Salesforce using the wizard. 


The metadata file you download will include a certificate. For Access Manager to trust or use this 
certificate, the trusted root certificate chain that minted the certificate must exist in the Access 
Manager certificate trust stores. 


4 Import certificate in Access Manager, for example, Salesforce.com. 


4a Open the downloaded metadata . xml file with a file editor and search for the certificate in 
the X509Certificate element (between <ds:X509Certificate> and </ds:X509Certificate>). 


4b Copy the information into its own file and give ita .cer file extension. Windows will 
recognize this as a certificate. 


4c Double click and open the file. 
4d Click Certification Path to see the chain of authority for the certificate. 
You will need the trusted root certificate for every CA in the chain that you see listed. 


4e In the example above, select the VeriSign Class 3 International Server CA - G3 and click 
View Certificate. 


4f Click Details. 
5 You can now export the CA trusted root certificate. 
5a Click Copy to File.... This will launch the Windows Certificate Export Wizard. 
5b Select .DER encoded when prompted. Give the file a name and save. 
5c Repeat this process for every CA in the certificate path chain. 


5d Use the Access Manager Administration Console to import the resulting CA trusted root 
certificates into your Access Manager keystores. 


After importing, add these certificates into Identity Server Keystore. For more information, see 
Section 14.2, “Adding a Certificate to a Keystore,” on page 957. 


Ensure to add Root certificate of Salesforce into your OCSP trust store else, OCSP validation fails 
and Identity Server displays an error. 


Integrating Shibboleth Identity Provider With Access Manager 


You can establish a single sign-on exchange between Access Manager SAML 2 service provider and 
a Shibboleth SAML 2 identity provider. 


For more information, see Integrating Access Manager with Shibboleth’s Identity Provider Server. 
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5.2.12 


5.2.12.1 


5.2.12.2 


Integrating Amazon Web Services with Access Manager 


Access Manager now enables you to federate with the Amazon Web Services (AWS) with the help of 
a wizard. The wizard allows you to configure the required options and relies upon the default settings 
for the other federation options. 


Integrating AWS with Access Manager includes the following steps: 


+ 


+ 


Section 5.2.12.1, “Enabling Web Single Sign-On in the AWS Console,” on page 620 
Section 5.2.12.2, “Configuring AWS as a Service Provider in Access Manager,” on page 620 


Enabling Web Single Sign-On in the AWS Console 


Before you integrate AWS in Access Manager, you must enable web single sign-on (sso) in the AWS 
console. To enable web sso, perform the following steps: 


1 
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Download the Access Manager SAML 2.0 metadata by accessing https :// 
<www. idp.com:8443>/nidp/sam12/metadata. Save into local file and rename it as nam-sam12- 
metadata. xml. 


Open the AWS console by accessing: https://console.aws.amazon.com/console/home. 
Log in to AWS. 
Click Security & Identity > Identity & Access Management. 
Click Identity Providers. 
Click Create Provider. 

6a Provider Type: Select SAML. 

6b Provider Name: Specify a name. For example, NAM-IDP. 

6c Metadata Document: Select the file that you saved in Step 1 on page 620. 


7 Verify the provider information and click Create. 
8 On the dashboard, click Roles. 
9 Click Create New Role. 


Specify a role name. 
Click Next. 


Select Role for Identity Provider Access > Grant Web Single Sign-On (WebSSO) access to 
[SAML providers]. 


Click Next Step. 

On the Attach Policy page, select the desired policies. Click Next Step. 
Review the role information. Make a note of the Role ARN and Trusted Entries. 
Click Create Role. 


Configuring AWS as a Service Provider in Access Manager 


1 
2 
3 


Click Devices > Identity Servers > Edit > SAML 2.0. 
Click New > Service Provider. 
Specify the following details: 


Provider Type: Select Amazon Web Services. 
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By default, the Metadata Text source is selected and the Text field is pre-filled with the metadata 
XML. 


Name: Specify a name for the provider and click Next. 


Role ARN: Specify the role ARN. For example, specify arn: aws: iam: 625143326143: role/ 
MyAdmin. 

Trusted SAML Provider ARN: Specify the trusted SAML provider ARN. For example, specify 
arn:aws: iam: 625143326143: saml-provider/idp1. 


To fetch ARN values, see “Enabling Web Single Sign-On in the AWS Console” on page 620. 


NOTE: The Role ARN and Trusted SAML Provider ARN parameters are used to create the 
attribute mapping. If you have configured multiple roles in AWS, you can add any Role ARN 
while creating a service provider. To modify the attribute set, see “Re-Mapping Attribute Sets” on 
page 621. 


4 Review the metadata certificates and click Finish. 
5 Click OK, then update Identity Server. 


Re-Mapping Attribute Sets 


By default, the AWS wizard creates an attribute set with the name AmazonwebServices. This attribute 
set has the following mappings: 


1 Constant Value: It is created using the Role ARN and trusted SAML provider. It is mapped to 
Role. 


For example: if Role ARN is arn: aws: iam: :638116851885: role/NewRole and the Trusted 
SAML Provider ARN is arn: aws: iam: :638116851885: saml-provider/NAM-IDP, then, the 
constant value is arn: aws: iam: :638116851885: role/ 

NewRole, arn: aws:iam: :638116851885 : saml-provider/NAM-IDP. This is mapped to the Role. 


NOTE: When multiple roles are configured in AWS, create a virtual attribute to change the Role 
ARN dynamically depending on the user. After creating the virtual attribute, create the 
corresponding attribute mapping. For more information, see use case 3 in “Sample JavaScripts 
with Examples” on page 99. 


2 LDAP Attribute: It is the givenName mapped to the Remote Attribute RoleSessionName. You can 
also map any other attribute instead of the givenName. 


If you want to use any other LDAP attribute to be mapped for RoleSessionName, perform the 
following steps: 


1 Click Devices > Identity Server > Shared Settings > Attribute Sets > AmazonWebServices > 
Mapping. 

In the attribute list, select the existing LDAP attribute set. 

Click Delete. 

Click Apply > OK. 

Click New. 

In Add Attribute Mapping, specify the following details: 
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5a Local attribute: Select a local attribute from the available list. 

5b Remote Attribute: Specify RoleSessionName. 

5c Remote nameSpace: Specify http://aws.amazon.com/SAML/Attributes/ 
6 Click OK > Finish. 
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7 Click Devices > Identity Servers > Edit > SAML 2.0. 

8 Select AWS and click Attributes. 

9 Select the new attribute set from Available and move it to Send with authentication. 
10 Click OK, then update Identity Server. 


Re-Importing The Metadata 


The AWS metadata has a validity associated with it. You need to re-import the metadata before the 
license expires. To re-import the metadata, perform the following steps: 

Click Devices > Identity Servers > Edit > SAML 2.0. 

Under Trusted provider, click AWS service provider. 

In Metadata, click Reimport. 
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Specify the following: 

4a Provider Type: Select General. 

4b Source: Select Metadata text. 

4c Name: Name for the service provider is displayed by default. 


4d Text: Fetch the metadata from: https://signin.aws.amazon.com/static/saml- 
metadata. xml. Remove the string content <KeyDescriptor use="Signing"> .... </ 
KeyDescriptor>. Copy this edited metadata and paste it in Text. 


5 Click Next. 
6 Confirm metadata certificates, then click Finish. 
7 Update Identity Server. 


5.2.13 Configuring Single Sign-On for Office 365 Services 


Access Manager provides single sign-on access to Office 365 services such as Exchange Server, 
SharePoint Online and Lync without using ADFS (Active Directory Federation Services). You can use 
your existing enterprise credentials to access any of the Office 365 services without having to 
remember multiple passwords or sign in multiple times to access different services. You can sign in 
once with an existing password and Access Manager grants you access to all services. 


This single sign-on access is achieved by implementing Passive or Active authentication by using 
WS-Federation, WS-Trust, and SAML 2.0 protocols. 


A trust model is set up for Access Manager and Office 365 to communicate with each other. Access 
Manager, configured as an identity provider, allows Office 365 to trust it for authentication. Office 365 
configured as a service provider, consumes authentication assertions from Access Manager. 


Access Manager supports single sign-on to the following Office 365 applications: 


¢ SharePoint 

+ Office 365 Portal 

+ Outlook Web Access 

+ Lync 2010 

¢ Lync 2013 

¢ Skype for Business 2015 
¢ Outlook 2013 
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5.2.13.1 


5.2.13.2 


Topics include: 


¢ Section 5.2.13.1, “Passive and Active Authentication,” on page 623 


¢ Section 5.2.13.2, “Configuring Active and Passive Authentication By Using WS-Trust and WS- 
Federation Protocols,” on page 623 


¢ Section 5.2.13.3, “Configuring Federation with Office 365 Services for Multiple Domains,” on 
page 626 


¢ Section 5.2.13.4, “Configuring an Office 365 Domain That Supports Passive Federation by using 
SAML 2.0,” on page 629 


¢ Section 5.2.13.5, “Useful Resources,” on page 636 
¢ Section 5.2.13.6, “Troubleshooting Scenarios,” on page 636 
¢ Section 5.2.13.7, “Sample Tokens,” on page 638 


Passive and Active Authentication 


In a Passive authentication scenario, the user signs in through a Web form displayed by the identity 
provider and the user is requested to log in. In Active authentication scenario, the user is 

authenticated using thick clients. As the thick client does not support redirection, Office 365 gets the 
credentials and validates the authentication with Access Manager by communicating directly with it. 


Passive authentication is supported by using the WS-Federation protocol and supports sign-in to 
Office 365 using the Web interface. The clients includes the Office 365 portal, SharePoint Online, 
Outlook Web Access, and the Office Web Apps. You can achieve passive authentication using either 
SAML 2.0 or WS-Federation protocol. 


Active authentication is supported by using the WS-Trust protocol and supports sign-in to Office 365 
using Office client applications. The clients includes Outlook, Lync, Word, Excel, PowerPoint, and 
OneNote. If you are using Microsoft Exchange, you can use SAML 2.0 but for active authentication, 
WS-Trust is the recommended protocol. 


Configuring Active and Passive Authentication By Using WS-Trust 
and WS-Federation Protocols 


Using the wizard, when you configure an Office 365 domain with WS-Trust protocol it creates the 
following two domains: 


+ A domain preconfigured for active authentication using WS-Trust protocol 
+ A domain preconfigured for passive authentication using WS-Federation protocol. 


If your business needs demand using a domain based on SAML 2.0 protocol, you can configure a 
domain manually using the steps in “Configuring an Office 365 Domain That Supports Passive 
Federation by using SAML 2.0” on page 629 


The following sections cover the details about how to configure a domain by using WS-Trust and WS- 
Federation protocols: 


¢ “Prerequisite” on page 624 
¢ “Configuring an Office 365 Domain By Using WS-Trust Protocol” on page 624 
¢ “Configuring an Office 365 Domain to Federate with Access Manager” on page 624 
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Prerequisite 


Use the following steps to verify that WS-Trust and WS-Federation protocols are enabled in Access 
Manager: 


1 Click Devices > Identity Servers > Edit. 


2 In the Enabled Protocols section, ensure that WS-Trust and WS-Federation protocols are 


selected. 


Configuring an Office 365 Domain By Using WS-Trust Protocol 


When you configure a new Office 365 domain by using the WS-Trust protocol, it creates a domain 
preconfigured for Active authentication and also creates a WS-Federation Service Provider that is 
preconfigured for Passive authentication. 


1 Click Devices > Identity Servers > Edit > WS-Trust > Service Provider Domain. 


2 Click New > Office 365 Domain and specify a name to identify the domain. This domain is by 


default configured with ImmutablelD and Attribute Set information and a Service Provider with 
the same name as the Office 365 domain is automatically created. 


An authentication method Name/Password - Form-WebService is created and this is selected 
for WS-Trust. This method ensures that an email address/password is accepted for 
authentication. 


Click the domain name to make further modifications. 
For more details, see link “Modifying Service Providers” on page 573 


Click the WS-Federation tab and verify that a new Service Provider with the same name as the 
Office 365 domain is created. This Service Provider is preconfigured with Attribute Set 
information and Authentication Response for the Passive authentication. 


Configuring an Office 365 Domain to Federate with Access Manager 


+ 


+ 


+ 


“Prerequisite” on page 624 
“Enabling Federation Settings in Office 365 Domain” on page 625 
“Verifying Single Sign-On Access” on page 625 


Prerequisite 


Ensure that the following requirements are met before configuring an Office 365 domain: 


+ 


Identity Server must be accessible from outside the firewall so that the Office 365 domain can 
communicate with Identity Server. 


Sign up for an Office 365 account. 


To single-sign on to any of the Office 365 applications, ensure that you download it from the 
Office 365 portal. 


Create a federated domain in Office 365 and prove ownership of it. This ensures that you add 
your company domain into the Office 365 domain. For more information, see Adding and 
Verifying a Domain for Office 365. 


Ensure that the Windows 7 or Windows 8 workstations do not have the Active Directory 
Federation Service 2.0 snap-in installed. 


Ensure that the Identity Server Base URL SSL certificate is issued by a well-known external 
certification authority (CA). 
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¢ Install Microsoft Live Sign-in Module to help manage and establish a remote session with the 
Office 365 account that is created to manage the Office 365 domain. To download, go to 
Microsoft Downloads Center. 


¢ Install Microsoft Azure Active Directory Module. To download, go to Manage Azure AD using 
Windows PowerShell. 


Enabling Federation Settings in Office 365 Domain 


Run the following commands in Powershell by modifying the commands with your domain name as 
per your setup. The domain name in the example is namtest .com. 


1 From the Start Menu launch Windows Azure Active Directory Module for Windows PowerShell. 


2 Run $cred=Get -Credential. Enter your cloud service administrator account credentials. 


3 Run Connect-MsolService -Credential $cred 


For example, if the name of the domain is namtest . com and the Base URL of Identity Server is 
https://namtest.com/nidp/, execute the following commands at the Powershell prompt: 


NOTE: In this example, the Base URL the port is not specified as it uses the default port 443. If 
you are using a different port, specify the port with the Base URL. 


For example: https://namtest.com/nidp/ 
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8. 


$dom = "namtest.com" 

$url = "https://namtest.com/nidp/wsfed/ep" 

$ecpUrl = "https://namtest.com/nidp/wstrust/sts/active12" 

$uri = "https://namtest.com/nidp/wsfed/" 

$logouturl = "https://namtest.com/nidp/jsp/o365wsfedlogout.jsp" 
$mex = "https://namtest.com/nidp/wstrust/sts/mex" 


$cert = New-Object 
System.Security.Cryptography.xX509Certificates.Xx509Certificate2("name and 
path of the certificate") 


NOTE 


+ If the certificate used has a .crt extension ensure that you convert it to a .cer 
extension file. 


¢ While executing this command, ensure that you specify the path to the certificate within 
the double quotes. For example: “C: \local\netiq-off365-sign.cer” 


$certData = [system.convert]::tobase64string($cert.rawdata) 


4 Use the following cmdlet to update the settings of the single sign-on domain. 


Set-MsolDomainAuthentication -FederationBrandName $dom -Authentication 
Federated -PassiveLogOnUri $url -SigningCertificate $certData -IssuerUri $uri - 
ActiveLogOnUri $ecpUrl -LogOffUri $logouturl -MetadataExchangeUri $mex 


Verifying Single Sign-On Access 


Prerequisite: 


+ You need at least one user in Office 365 to verify that single sign-on is set up. If you have an 
existing user, ensure that the Immutable ID matches the GUID of the Access Manager user. 


For instance if your user store is eDirectory and you want to retrieve the GUID of an existing 
Access Manager user, execute the following command on the eDirectory server terminal: 
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ldapsearch -x -h 127.0.0.1 -p 389 -D cn=admin, 0=novell -w novell -b 
cn=anand, o=novell guid 


Where h is host, p is port, D is bind credential, w is password, b is search scope, and guid is the 
attribute to search. 


Create an Office 365 user with this GUID as the Immutable ID by using the following command in 
Powershell: 


new-msolUser -userprincipalName "useri@domain name" -immutableID "GUID of 
useri" - lastname "lastname of user 1" -firstname user1 -DisplayName "user1 
users" -BlockCredential $false -"LicenseAssignment testdomain: ENTERPRISEPACK" 
-usageLocation "two letter country code[example: US, IN, DE, BE, GB etc]" -Password 
"password of the user" - LicenseAssignment validlicense. 


Procedure to verify: 


To verify that single sign-on is set up correctly, perform the following procedure in a server that is not 
added to the domain. 

1 Go to Microsoft Online Services (http://login.microsoftonline.com/). 

2 Log in with your corporate credentials. (For example : user1@namnetiq. in) 


If single sign-on is enabled, the password field is dimmed. You will instead see the following 
message: You are now required to sign in at <your company>. 


3 Select the Sign in at your company link. 
If you are able to sign in without errors, single sign-on is set up successfully. 


5.2.13.3 Configuring Federation with Office 365 Services for Multiple 
Domains 


You can now federate multiple parent domains with a single Access Manager cluster. This means that 
if the enterprise has users belonging to multiple domains, a single Access Manager cluster can 
handle the single sign-on requests for all the users for Office 365 services. 


For example: Let us assume you have users spread across two domains: user1@namtest.com and 
user2@namnetig.in. When useri@namtest.com and user2@namnetiq.in access Office 365 
services, the same Access Manager identity provider automatically forms the response with the 
corresponding Issuer URI and sends it to corresponding domains configured in the Office 365 
service. 


¢ “Creating Multiple Domains in Office 365 and Establishing Federation with Access Manager” on 
page 626 
¢ “Configuring Federation for Multiple Domains that Include Child Domains” on page 628 


Creating Multiple Domains in Office 365 and Establishing Federation with 
Access Manager 


1 Ensure that you meet the prerequisites for creating a domain. For more information, see 
“Prerequisite” on page 624. 


2 Create a new Office 365 domain and verify it. For more information see Adding and Verifying a 
Domain for Office 365. (http://office365support.ca/adding-and-verifying-a-domain-for-the-new- 
office-365/) 
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NOTE: Office 365 does not support creating a child domain if federation configuration for parent 
domain is already established by using powershell. Ensure that you add all child domains from 
the Office 365 admin center before establishing federation for the parent domain. 


For more information about establishing federation when there are multiple domains and a child 
domain, see “Configuring Federation for Multiple Domains that Include Child Domains” on 
page 628. 


According to the example used in section Enabling Federation Settings in Office 365 Domain, we 
have an existing domain named namtest . com. 


To create a new domain named namnetiq. in, run the following commands in Powershell by 
modifying the commands with your domain name as per your setup. 


3a Run $cred=Get -Credential. Enter your cloud service administrator account credentials. 
3b Run Connect -MsolService -Credential $cred 


For example, if the name of the domain is namnetiq.in and the Base URL of Identity 
Server is https://namnetiq.in/nidp/, execute the following commands at the 
Powershell prompt: 


NOTE 


+ In the following example, port is not mentioned as it uses 443. However, if you are 
using port 8443, specify the port with the Base URL as follows: 


For example: https: //namnetiq.in:8443/nidp/ 


+ When you add additional domains to Office 365 using Powershell commands, the 
variables $certdata, $url, $ecpurl, $logouturl,and $mex must contain the details 
provided for the existing domain. If you configure a new domain, change the values of 
$dom and the $uri 


. $dom = "namnetiq.in" 

$url = "https://namtest/nidp/wsfed/ep" 

. $ecpUrl = "https://namtest.com/nidp/wstrust/sts/active12" 

$uri = "https://namnetiq.in/nidp/wsfed/" 

. $logouturl = "https://namtest.com/nidp/jsp/o365wsfedlogout.jsp" 


$mex = "https://namtest.com/nidp/wstrust/sts/mex" 


NOOR WD = 


. $cert = New-Object 
System.Security.Cryptography.xX509Certificates.X509Certificate2("name 
and path of the certificate") 


NOTE 


+ If the certificate used has a .crt extension ensure that you convert it toa .cer 
extension file. 


+ While executing this command, ensure that you specify the path to the certificate 
within the double quotes. For example: “C:\local\netiq-off365-sign.cer” 


8. $certData = [system.convert]::tobase64string($cert.rawdata) 


3c Use the following cmdlet to update the settings of the single sign-on domain. 
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Set-MsolDomainAuthentication -FederationBrandName $dom -Authentication 
Federated -PassiveLogOnUri $url -SigningCertificate $certData -IssuerUri 
$uri -ActiveLogOnUri $ecpUrl -LogOffUri $logouturl -MetadataExchangeUri 


$mex 


To configure any more domains, follow the same steps. Ensure that the Issuer URI includes 
the UPN of the domain. For example. If you are configuring a domain named support. in, 
the Issuer URI will be https: //support.in/nidp/wsfed/ 


4 Go to Devices > Identity Servers > Edit > Options and ensure that the value for STS 
OFFICE365 MULTI DOMAIN SUPPORT AUTO is configured as true. 


This property enables users to access Office 365 services using the Issuer URI specific to the 


domain they belong to. 


Configuring Federation for Multiple Domains that Include Child Domains 


Consider a scenario where you already have users as part of namtest.com and namnetiq.in. You 
now need to create a child domain support .namnetiq.in under namnetiq. in. In this case no 
federation settings are available in Office 365 for the child domain. The federation setting for the 
parent domain is used. So, it is important that the Issuer URI is not automatically changed to the User 
Principal Name of the user. The Issuer URI must be set to the parent domain Issuer URI. For the child 
domain support .namnetiq.in, the Issuer URI will be https: //namnetiq.in/nidp/wsfed/ 


1 Click Devices > Identity Servers > Edit > Options > New. 


Property Type 


STS CHANGE ISSUER 


STS OFFICE365 MULTI DOMAIN 
SUPPORT AUTO 


2 Click OK > Apply. 
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Property Value 


Specify the value in this format: SPentityID:UPNDomain -> new 
Issuer ID. 


For example, 
urn: federation:MicrosoftOnline:support.namnetiq.in -> 
https://namnetiq.in/nidp/wsfed/ 


For example, 
urn: federation:MicrosoftOnline:support.namnetiq.in -> 
https://namnetiq.in/nidp/wsfed/ 


In case of multiple child domains, add each parent domain and child 
domain separated by comma. For example, if namnetiq.in is the 
parent domain and support.namnetiq.in and engineering.namnetiq.in 
are the child domains, specify the following entries: 


urn: federation:MicrosoftOnline:namnetig.in -> https:/ 
/namnetiq.in/nidp/wsfed/, 

urn: federation:MicrosoftOnline:support.namnetiq.in -> 
https://namnetiq.in/nidp/wsfed/, 

urn: federation:MicrosoftOnline: engineering.namnetiq.i 
n -> https://namnetigq.com/nidp/wsfed/ 


Select false. 


This ensures that the Issuer URI is formed based on the UPN of the 
parent domain. 


5.2.13.4 Configuring an Office 365 Domain That Supports Passive Federation 
by using SAML 2.0 


+ “Prerequisite” on page 629 
¢ “Configuring an Office 365 Domain to Federate with Access Manager” on page 629 


Prerequisite 
Ensure that SAML 2.0 is enabled in Access Manager. 


1 Click Devices> Identity Servers > Edit. 
2 In the Enabled Protocols section, verify whether SAML 2.0 is selected. 


Configuring an Office 365 Domain to Federate with Access Manager 


+ “Prerequisite” on page 629 

¢ “Setting Up Office 365 Services” on page 630 

¢ “Establishing Trust Between an Identity Provider and a Service Provider” on page 630 
¢ “Configuring Specific Attributes as ImmutablelD” on page 631 

¢ “Configuring Desktop Email Client to Access Office 365 Emails” on page 632 

¢ “Configuring Desktop Email Client to Access Office 365 Emails” on page 633 

¢ “Verifying Single Sign-On Access” on page 635 


Prerequisite 
Ensure that the following requirements are met before configuring an Office 365 domain: 


¢ Sign up for an Office 365 account. 


¢ To single-sign on to any of the Office 365 applications, ensure that you download it from the 
Office 365 portal. 


¢ Create a federated domain in Office 365 and prove ownership of it. By doing this you add your 
company domain into the Office 365 domain. For more information, see Adding and Verifying a 
Domain for Office 365. 


+ Ensure that the Windows 7 or Windows 8 workstations do not have the Active Directory 
Federation Service 2.0 snap-in installed. 


¢ Ensure that the Identity Server Base URL SSL certificate is issued by a well-known external 
certification authority (CA). 


¢ Install Microsoft Live Sign-in Module to help manage and establish a remote session with the 
Office 365 account that is created to manage the Office 365 domain. To download, go to 
Microsoft Downloads Center. 


¢ Install Microsoft Azure Active Directory Module. To download, go to Manage Azure AD using 
Windows PowerShell. 
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Setting Up Office 365 Services 


Office 365 is preconfigured to establish federation with an external service providers. 


Perform the following steps to create a trusted service provider: 


1 
2 
3 
4 


5 


Click Devices> Identity Servers > Edit. 

Click SAML 2.0 > New >Service Provider. 

Select Provider Type as Office 365. Ensure that Source is selected as the Metadata Text. 
Specify a name for the Office 365 domain. The XML metadata is automatically populated in the 


Text field. Click Next. 


Confirm the certificates and click Finish to save the changes. 


Establishing Trust Between an Identity Provider and a Service Provider 


You can configure Office 365 domains federations by using the Microsoft Online Services Module. 
You can use the Microsoft Online Services Module to run a series of cmdlets in the Windows 
PowerShell command-line interface to add or convert domains for single sign-on. 


Each Active Directory domain that you want to federate by using Access Manager must either be 
added as a single sign-on domain or converted to be a single sign-on domain from a standard 
domain. Adding or converting a domain sets up a trust between Access Manager and Office 365. 


Adding a Domain: 


To add a domain to Office 365, perform the following steps: 
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Log in to Office 365 as an administrator. 

On the Administrator page, click Management > Domains > Add a domain. 
Specify the domain name that you want to add. 

Click Next. 

Verify the domain name. 


For more information about how to verify a domain, see Verify your domain and change name 
servers. 


6 Select appropriate services. 


Configure the DNS records on the domain registrar for other services. 


NOTE: Do not configure the new domain to the primary domain. Using the Set- 
MsolDomainAuthentication command to set the domain as a federated domain results in an 
error if the domain is the default domain. 


For more information, see Add a domain to Office 365. 


Converting a standard domain to a federated domain: To convert a standard domain to a 
federated domain, perform the following steps: 


1 
2 
3 


Open the Microsoft Online Services Module from the Start menu. 
Run $cred=Get -Credential. Enter your cloud service administrator account credentials. 
Run Connect-MsolService -Credential $cred. 


This cmdlet connects you to the cloud service. Creating a context that connects you to the cloud 
service is required before running any of the additional cmdlets installed by the tool. 
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For example, if the name of the domain you are converting to a single sign-on domain is 
namtest.com, and the base URL of Identity Server is https://namtest.com:8443/nidp, execute the 
following commands at the Powershell prompt: 


1. $dom = "namtest.com" 

2. $url = "https://namtest.com:8443/nidp/sam12/sso" 

3. $ecpUrl = "https://namtest.com:8443/nidp/sam12/soap" 

4. $uri = "https://namtest .com:8443/nidp/sam12/metadata" 

5. $logouturl = "https://namtest.com:8443/nidp/jsp/o365Logout .jsp" 
6. $cert = New-Object 


System.Security.Cryptography.xX509Certificates.Xx509Certificate2("name and 
path of the certificate") 


NOTE: While executing this command, ensure that you specify the path to the certificate 
within the double quotes. For example: “C:\local\netiq-off365-sign.cer” 


7. $certData = [system.convert]::tobase64string($cert.rawdata) 


4 Use the following cmdlet to update the settings of the single sign-on domain: 


Set-MsolDomainAuthentication -FederationBrandName $dom -Authentication Federated - 
PassiveLogOnUri $url -SigningCertificate $certData -IssuerUri $uri -ActiveLogOnUri $ecpUrl - 
LogOffUri $logouturl -PreferredAuthenticationProtocol SAMLP 


NOTE: Ensure that there are no spaces after the hyphen if you are copy pasting the command. 


Configuring Specific Attributes as ImmutableID 


By default, Office 365 uses GUID as the ImmutablelD. If you want to use any other attribute as the 
ImmutablelD of the Office 365 user, configure and then add a property name/value pair. 
1 In Administration Console, go to Identity Server and select an Identity Server. 
2 Select SAML 2.0 and then select the service provider you created. 
3 Select Options and click New. 
4 Add a property name/value pair as follows: 
Property Name: SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME 
Property Value: title 


The title you specify in the Property Value must be base64 encoded and stored in the user store. This 
value must be used as ImmutablelD while creating a user in Office 365. 


Configuring Virtual Attributes as ImmutablelD 
Virtual attributes can be helpful in many scenarios: 


+ Ifthe attribute has clear text value, virtual attribute can be used to dynamically convert it into a 
base64 value 


+ Retrieve the attribute from an external datasource and use it as the ImmutablelD 
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To use virtual attribute as ImmutablelD, perform the following steps: 
1 Create a virtual attribute. For information about how to create a virtual attribute, see “Managing a 
Virtual Attribute” on page 94. 


2 Go to Devices > Identity Servers > Servers > Edit > SAML 2.0 > Service Provider > Options and 
add the following property for Office 365: 


+ Property Name: SAML2_OFFICE365 NAMEID_ATTRIBUTE_NAME 
+ Property Value: Specify the name of the virtual attribute 


3 Add the virtual attribute created in step 1 to the attribute set created for the SAML 2.0 service 
provider configuration for Office 365. This ensures that the name specified in 
SAML2_OFFICE365 NAMEID_ATTRIBUTE_NAME is mapped to the virtual attribute with that 
value. If the virtual attribute is not added to the attribute set, Access Manager considers the 
name as a normal LDAP attribute name. 


Configuring Desktop Email Client to Access Office 365 Emails 


You can configure your desktop email client to access Office 365 emails. The email clients must use 
a basic authentication and a supported exchange access method such as IMAP, POP, Active Sync, 
and MAPI. 


The following are the list of email clients supported for this configuration: 
¢ Microsoft Outlook 2007 
¢ Microsoft Outlook 2010 
¢ Thunderbird 8 and 9 
+ The iPhone (various iOS versions) 
+ Windows Phone 7 


NOTE: You can download the email clients from the download section of Office 365. 


These steps are explained with an example where the federated domain name is namtest.com and 
the base URL is https://namtest.com:8443/nidp. Replace the domain name and base URL based on 
your system configuration. 


1 Open the Microsoft Online Services Module. 
2 Run the following command: 


$cred=Get -Credential 


Specify your cloud service administrator account credentials. 
3 Run the following command: 


Connect-MsolService -Credential $cred 


This cmdlet connects you to the cloud service. 
4 Execute the following command to check the existing domain federation settings: 


Get-MsolDomainFederationSettings -DomainName namtest.com 


Substitute namtest.com with your domain name before executing this command. 


In the output, look for the ActiveLogOnUri parameter. 
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For Identity Server base URL https://namtest .com:8443/nidp, the value of the 
ActiveLogOnuUri must be https://namtest .com:8443/nidp/sam12/soap. The 
ActiveLogOnuri is dependent on the base URL of Identity Server. 


If the value of ActiveLogOnUri in the command output is https://namtest .com:8443/nidp/ 
sam12/soap, go to Step 5 without modifying the configuration. 


(Conditional) If the ActiveLogOnUri is not https://namtest .com:8443/nidp/sam12/soap, 
execute the following command. Substitute namtest.com and port 8443 with your domain name 
and port number respectively before executing the following command. 


Set-MsolDomainFederationSettings -DomainName namtest.com -ActiveLogOnUri "https:// 
namtest.com:8443/nidp/saml2/soap" -preferredauthenticationprotocol SAMLP 


5 Create a new email account in your email client and enter your Office 365 email ID. 


NOTE: Configure Outlook related DNS settings before using email clients. You can configure 
these settings after adding the domain on the Office 365 port page. 


6 The system prompts for specifying the basic authentication. Specify Access Manager 
credentials. 


The email account is created after successful authentication. 


NOTE: While logging in to the new email account, enter Access Manager credentials. 


Configuring Desktop Email Client to Access Office 365 Emails 


You can configure your desktop email client to access Office 365 emails. The email clients must use 
a basic authentication and a supported exchange access method such as IMAP, POP, Active Sync, 
and MAPI. 


The following are the list of email clients supported for this configuration: 


¢ Microsoft Outlook 2007 

¢ Microsoft Outlook 2010 

¢ Thunderbird 8 and 9 

+ The iPhone (various iOS versions) 
+ Windows Phone 7 


NOTE: You can download the email clients from the download section of Office 365. 


These steps are explained with an example where the federated domain name is namtest.com and 
the base URL is https://namtest.com:8443/nidp. Replace the domain name and base URL based on 
your system configuration. 


1 Open the Microsoft Online Services Module. 
2 Run the following command: 


$cred=Get -Credential 


Specify your cloud service administrator account credentials. 
3 Run the following command: 


Connect-MsolService -Credential $cred 


This cmdlet connects you to the cloud service. 
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4 Execute the following command to check the existing domain federation settings: 
Get-MsolDomainFederationSettings -DomainName namtest.com 


Substitute namtest.com with your domain name before executing this command. 
In the output, look for the ActiveLogOnUri parameter. 


For the Identity Server base URL https://namtest .com:8443/nidp, the value of the 
ActiveLogOnUri must be https://namtest .com:8443/nidp/sam12/soap. The 
ActiveLogOnuri is dependent on the base URL of the Identity Server. 


If the value of ActiveLogOnUri in the command output is https://namtest .com:8443/nidp/ 
sam12/soap, go to Step 5 without modifying the configuration. 


(Conditional) If the ActiveLogOnUri is not https://namtest .com:8443/nidp/sam12/soap, 
execute the following command. Substitute namtest.com and port 8443 with your domain name 
and port number respectively before executing the following command. 


Set-MsolDomainFederationSettings -DomainName namtest.com -ActiveLogOnUri "https:// 
namtest.com:8443/nidp/sam12/soap" -preferredauthenticationprotocol SAMLP 


5 Create a new email account in your email client and enter your Office 365 email ID. 


NOTE: Configure Outlook related DNS settings before using email clients. You can configure 
these settings after adding the domain on the Office 365 port page. 


6 The system prompts for specifying the basic authentication. Specify Access Manager 
credentials. 


The email account is created after successful authentication. 


NOTE: While logging in to the new email account, enter Access Manager credentials. 


Configuring Specific Attributes as ImmutablelD 


By default, Office 365 uses GUID as the ImmutablelD. If you want to use any other attribute as the 
ImmutablelD of the Office 365 user, configure and then add a property name/value pair. 
1 In Administration Console, go to Identity Server and select an Identity Server. 
2 Select SAML 2.0 and then select the service provider you created. 
3 Select Options and click New. 
4 Add a property name/value pair as follows: 
Property Name: SAML2_OFFICE365_NAMEID_ATTRIBUTE_NAME 
Property Value: title 


The title you specify in the Property Value must be base64 encoded and stored in the user store. This 
value must be used as ImmutablelD while creating a user in Office 365. If the value is in a clear text 
format, you have to use virtual attributes to convert it into a base64 format. 
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To use virtual attribute as ImmutablelD, perform the following steps: 
1 Create a virtual attribute. For information about how to create a virtual attribute, see “Managing a 
Virtual Attribute” on page 94. 


2 Ensure that the final value of the virtual attribute is the base64 encoded value. You can achieve 
it in any of the following ways: 


+ Configure a virtual attribute to retrieve a value stored in the clear text format from an 
attribute source (LDAP or database) 


+ Transform the value into the base 64 encoded format by using the advanced JavaScript 
option 


3 Go to Devices > Identity Servers > Servers > Edit > SAML 2.0 > Service Provider > Options and 
add the following property for Office 365: 


+ Property Name: SAML2_OFFICE365 NAMEID_ATTRIBUTE_NAME 
+ Property Value: Specify the name of the virtual attribute 


This ensures that the NAMEID value is fetched based on the property name. Currently, the name 
is considered as a user attribute. 


4 Add the virtual attribute created in step 1 to the attribute set created for the SAML 2.0 service 
provider configuration for Office 365. This ensures that the name specified in 
SAML2_OFFICE365 NAMEID_ATTRIBUTE_NAME is mapped to the virtual attribute with that 
name. If the virtual attribute is not added to the attribute set, Access Manager considers the 
name as a normal LDAP attribute name. 


Verifying Single Sign-On Access 


You need at least one user in Office 365 to verify that single sign-on is set up. If you have an existing 
user, ensure that the Immutable ID matches with the GUID of the Access Manager user. 


Prerequisite: 


+ You need at least one user in Office 365 to verify that single sign-on is set up. If you have an 
existing user, ensure that the Immutable ID matches the GUID of the Access Manager user. 


For instance, if your user store is eDirectory and you want to retrieve the GUID of an existing 
Access Manager user, execute the following command on the eDirectory server terminal: 


ldapsearch -D cn=<context> -w <password> -b <search base> cn=<name of the user> 
GUID | grep GUID 


Create an Office 365 user with this GUID as the Immutable ID using the following command in 
Powershell: 


new-msolUser -userprincipalName "useri@domain name" -immutableID "GUID of 
useri" - lastname "lastname of user 1" -firstname user1 -DisplayName "user1 
users" -BlockCredential $false -"LicenseAssignment testdomain: ENTERPRISEPACK" 
-usageLocation "two letter country code[example: US, IN, DE, BE, GB etc]" -Password 
"password of the user". 


Verifying Single Sign-on: 


To verify that single sign-on is set up correctly, perform the following procedure in a server that is not 
added to the domain: 


1 Go to Microsoft Online Services. 
2 Log in with your corporate credentials. (For example : user1@namtest .com) 
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5.2.13.5 


5.2.13.6 


If single sign-on is enabled, the password field is dimmed. You will instead see the following 
message: You are now required to sign in at <your company>. 


3 Select the Sign in at your company link. 
If you are able to sign in without errors, single sign-on is set up successfully. 


Useful Resources 


The following list includes few useful resources for troubleshooting: 


¢ Office 365 Troubleshooting 

¢ Microsoft Remote Connectivity Analyzer 

¢ Sign in to Office 365 for Business 

¢ Description of Office 365 Desktop Setup Tool Logging Errors 


Links for Troubleshooting Sign-in issues with Microsoft Lync: 


e Describes how to troubleshoot sign-in issues with Microsoft Lync and Office 365 

¢ Describes how to clear the credential cache that can occur on some operating systems 

e Describes how Microsoft Lync can cache its connection endpoints and how to resolve the issue 
e Describes how to troubleshoot common issues between Lync for Mac and Office 365 


Troubleshooting Scenarios 


+ “WS-Trust and WS-Federation Scenarios” on page 636 
+ “SAML 2.0 Scenarios” on page 637 
¢ “Office 365 Domain Scenarios” on page 637 


WS-Trust and WS-Federation Scenarios 


Issue in Setting Up a Domain for Federation 


If you try to set a primary domain for federation by running the Set -MsolDomainAuthentication 
command, it throws the following error: 


Set-MsolDomainAuthentication: You cannot remove this domain as the default domain 
without replacing it with another default domain. Use the Set-MsolDomain cmdlet to 
set another domain as the default domain before you delete this domain. 


To fix this issue, change the default domain by performing the following steps: 


1 In the Office 365 portal, click Organization Name on the Admin page. 
2 Click Edit. 
3 Select a new default domain. 


Set-MsolDomainAuthentication : You cannot remove this domain as the default domain 
without replacing it with another default domain 


If you get this error it indicates that you attempted to delete the default domain without replacing it 
with another domain. 


Use the Set -MsolDomain cmdlet to set another domain as the default domain before you delete this 
domain. 
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After upgrading iOS Apps to the Latest Version, Single Sign-On to Office 365 Services Fail 
To establish single sign-on from iOS apps to Office 365 services, perform the following steps: 


1 Click Devices > Identity Servers > Edit > Local > Contract. 
2 Specify a name to identity the contract. 


3 Specify the URI as http://schemas.microsoft .com/ws/2008/06/identity/ 
authenticationmethod/password. 


4 Select Name/Password - Form - WebService method. 


SAML 2.0 Scenarios 
¢ “SSO to MicroSoft Services Fails” on page 637 


¢ “Issue in Setting Up a Domain for Federation” on page 637 
SSO to MicroSoft Services Fails 
SSO fails at Microsoft with this error: 
Your organization could not sign you in to this service 
Perform the following steps to fix this issue: 

¢ Verify that the attributes are configured properly. 


You can also use the SAML tracer plug-in Firefox to review the SAML assertion sent to 
Office365. 


¢ Verify that federation settings are using the Get-MsolDomainFederationSettings - 
DomainName <YOUR DOMAIN> command. 


Issue in Setting Up a Domain for Federation 


If you try setting up a primary domain for federation by running the Set -MsolDomainAuthentication 
command, it throws the following error: 


Set-MsolDomainAuthentication: You cannot remove this domain as the default domain 
without replacing it with another default domain. Use the Set-MsolDomain cmdlet to 
set another domain as the default domain before you delete this domain. 


To fix this issue, change the default domain by performing the following steps: 


1 Inthe Office 365 portal, click Organization Name on the Admin page. 
2 Click Edit. 
3 Select a new default domain. 


Office 365 Domain Scenarios 


¢ “Issues with the Directory Synchronization Tool” on page 638 
¢ “Active Profile Authentication Fails for Microsoft Exchange Clients” on page 638 


e “Microsoft Online Services Sign-In Assistant Installation Fails If Microsoft Office Professional 
Plus Is Installed” on page 638 


¢ “Single Sign-On to Office 365 Domain Fails” on page 638 
e “No License to Use Office 365 Services” on page 638 


¢ “After Initial Successful Authentication, Unending Loop While Logging into Lync Using Wrong 
Username and Password” on page 638 
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5.2.13.7 


Issues with the Directory Synchronization Tool 


+ Ifthe installation of the Directory Synchronization tool fails, check the Event Viewer. Installation 
may fail if the Microsoft Online Service Sign-In Assistant is already installed on the system. 


+ If you need to uninstall the Directory Synchronization tool, log off and then login. 
¢ If the Directory Synchronization tool is slow, increase RAM of the server. 


Active Profile Authentication Fails for Microsoft Exchange Clients 


If the active profile authentication fails for Microsoft Exchange (Outlook) clients, verify that the 
necessary DNS records have been added to your DNS. For more information, see Create DNS 
records at any DNS hosting provider for Office 365. 


Microsoft Online Services Sign-In Assistant Installation Fails If Microsoft Office Professional 
Plus Is Installed 


Manually install Microsoft Online Services Sign-In Assistant, if its installation fails after installing 
Microsoft Office Professional Plus with this message: 


"The Microsoft Online Services Sign In Assistant has experience an error. The error 
must be resolved before your subscription for this product can be verified. To 
retry subscription verification, first resolve error message 800704DD or try to 
manually install the Microsoft Online Services Sign In Assistant...." 


You can download the installer from MicroSoft Download Center. 


After installation is complete, relaunch the service to verify your Office 365 license. 


Single Sign-On to Office 365 Domain Fails 


If single sign-on fails, ensure that the ImmutableID and the User Principal Name (UPN) matches the 
Office 365 user. To get Office 365 user details, log in to using Powershell and execute the following 
command: 


Get-MsolUser -UserPrincipalName useri@namtest.com | fl * 


No License to Use Office 365 Services 


If you receive an error stating that the user does not have license to use Office365, Log in to Office 
365 as an administrator and assign required service licenses to the user. 


After Initial Successful Authentication, Unending Loop While Logging into Lync Using Wrong 
Username and Password 


After successfully authenticating to Office 365 client, if you attempt to login to the Lync client using an 
incorrect username and password, Lync client uses the details from the previous successful session 
and tries to get a token from Access Manager. This results in an unending loop. 


To resolve this issue, in the Lync client user interface, select the Delete my sign-in info option and log 
in again. 


Sample Tokens 


¢ “Sample SAML Token” on page 639 
+ “Sample WS-Trust Token” on page 641 
¢ “Sample WS-Federation Token” on page 643 


638 Configuring Authentication 


Sample SAML Token 
This section contains a sample XML for WS-Trust request and response. 
Request: 


<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_3ae4edbc-7ab5-48c7-a08e- 
b8d6e395e02c" IssueInstant="2012-09-09T08:41:35Z" Version="2.0" 
AssertionConsumerServiceIndex="0" ><saml:Issuer>urn: federation:MicrosoftOnline</ 
saml:Issuer><samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid- 
format :persistent"/></samlp:AuthnRequest> 


Response: 


<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
Consent="urn:oasis:names:tc:SAML:2.0:consent:obtained" Destination="https:// 
login.microsoftonline.com/login.srf" ID="idRuMHBv1VGqYUsw2Es -SbA5Ue08w" 
InResponseTo="_3ae4edbc -7ab5-48c7 -a08e-b8d6e395e02c" IssueInstant="2012-09- 
09T08:41:51Z" Version="2.0"> 
<saml:Issuer>https://www.netiqtst.com/nidp/sam12/metadata</saml: Issuer> 
<samlp:Status> 
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> 
</samlp:Status> 
<saml:Assertion ID="idF5JceWGWYwS3bOkmJS2wJuNqitU" IssueInstant="2012-09- 
09T08:41:51Z" Version="2.0"> 
<saml:Issuer>https://www.netiqtst.com/nidp/sam12/metadata</saml:Issuer> 
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
<ds:SignedInfo> 
<CanonicalizationMethod xmlns="http://www.w3.org/2000/09/xmldsig#" 
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> 
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-shai"/> 
<ds:Reference URI="#idF5JcewGWYwS3bOkmJS2wJuNqitU"> 
<ds:Transforms> 
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped- 
signature"/> 
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> 
</ds:Transforms> 
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#shai"/> 
<DigestValue xmlns="http://www.w3.org/2000/09/ 
xmldsig#">ZocFiEUYcdaOcKGRNcZYZqvmn1M=</DigestValue> 
</ds:Reference> 
</ds:SignedInfo> 
<SignatureValue xmlns="http://www.w3.org/2000/09/xmldsig#"> 
DLkK4Uv/4V1lwwKVz7XdDQOdUv8LtcryLv2U3K7q57AE7 Owk/NNsa4kP8Xdta36Y470j+XTV+atqoy 
YsMNIezySxaxMqoO1Fm+6PFfMH7Ht TV] 7FQ3n+VWwANgbIs3G7eaaV1pHdUs79/dBujS8baNmlZEBR 
2gGVMWCHOa1fTOSZO8yPt 9umeOPSYXpo2RdaoGk JCZUNVIiIWg6Ut LOZEKbY 6mP3IhrUJ70VHdbz 
yNBzhfTvOm71nz0JKpy+i8MeDUIuLOigTTIZ+c2SPceYhQc j 8umrdE4JCGEBYNIE52PaibRYgmLd 
roAKn56vLDjq04VnYVRGhgP/McZwYZr x+7E7qQ== 
</SignatureValue> 
<ds:KeyInfo> 
<ds:X509Data> 
<ds:x509Certificate> 
MIIFBZCCA++gAwIBAgIRAKdqzGhi9tecr yvMuy+QhgAwDQY JKOZIhVcNAQEFBQAwc j ELMAKGALUE 
BhMCROIxGZAZBgNVBAgTEkdyZwFOZXIgTWFuY2h1c3R1cjEQMA4GALUEBXMHU2FsZm9yZDEaMBgG 
ALUEChHMRQOONTORPIENBIEXxpbwWlOZWQxGDAWBgNVBAMTDOVzc2VudGLhbFNTTCBDQTAeFwOxMjA5 
MDCWMDAWMDBaFwOxMj EyMDY yMZU5NT LaMFExITAfBgNVBASTGERVbWFpbiBDb250cm9sIFZhbG1k 
YXRLZDERMA8GA1LUECXMIRnJ1ZSBTUQwxGTAXBgNVBAMTEHd3dy5uZXRpcxXRzdC5jb20wggEiMAOG 
CSqGSIb3DQEBAQUAA4 IBDWAWggEKAOIBAQCX6k7wnFUoyPt gS j O6xyQMHQt oxASBtHGASaOMxfZJ 
rHQ4wbJUqMEtrxYcz4JxFrLzE8qvlY5r7cwxx/yvsiFwHq2HdRY6KU6I12u0eRF/tRwf3r1222/X1 
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7wRbgdL43zd0yypjub9FKX1CxkaKucA1P+EVGTd7H8dF jMufOiKZYVBFg9tc JWBGpFOw5iwe/rjK 
6gQSXF13+Tpb69151susJFPMe3t O4wA4xXuyLlcJ/JIrxrj9xrEtwkmUcudTvEZRvJFnz3NYXcw0J8 
6aOJZSELH1VHr LY/44FVEQFj kr fr2u5RKGBJZ135xb2x5mkUSzzy4CSL5pO0fCsVOve7LKx/fAgMB 
AAG} ggG3MI IBSZAFBgNVHSMEGDAWgBTay+qtwWwhdzP/8J1TOSeVVxj j0+DAdBgNVHQ4EF gQUEj /C 
c5rqiBWiSzo9B8iJPdJnCpYwDgYDVROPAQH/BAQDAgWgMAWGA1UdEWEB/wQCMAAWNAYDVRO1BCOw 
KwY [KwYBBQUHAWEGCCSGAQUFBWMCBgor BgEEAY13CgMDBglghkgBhvhCBAEWRQYDVROgBD4wPDA6 
BgsrBgEEAbIxAQICBZArMCkGCCSGAQUFBwWIBFhiodHRwczovL3N1lY3VyZS5j b21vZG8uY29tLONQ 
UZA7BgNVHR8ENDAyMDCgLgAshipodHRw0i8vY3JsLmNvbW9kb2NhLmNvbS9Fc3N1lbnRpYwxTUOxD 
QS5j cmwwbgY IKwYBBQUHAQEEY j BgMDgGCCSGAQUFBZAChixodHRw0i8vY3JOLmNvbW9kb2NhLmNv 
bS9FC3N1bnRpYwxTUOxDQV8yLmNydDAkBggr BgEFBQcwAYYYaHROCDOVL29j c3AUY29tb2RvY2Eu 
Y29tMCkGALUdEQQiMCCCEHd3dy5uZXRpcXRzdC5jb22CDG51dG1LxdHNOLmNvbTANBgkqhkiG9wOB 
AQUFAAOCAQEAJOS/FEQgBMWvZQBSRRUSMBHMNbgDXP1fVPwJZnkf IHbb/wxwYK7AgA5ef0e1Alqz 
QD94kJ+W6IJZm4ripePJk7QLnNK2img JbOE7LdmwWQ3D05WQNSZKUK1FR+9e1P6xBN5ycXqtiEItScm 
hE7H2gynz4/ejLXZv8XsBkfsYnTOwwUmyTsqYPLmVk7ELFPiPGZsQcvpmSO9eoTQ8zabkQGj quzM 
NgGtXOMQBQgNO/7 IMghgmSRONduPguZoL310x84yKdf6H15cvbnH2w4cOn8vTkgCwUkB80NY1iTge 
6TFPwZS98PzVO8nxKSJWihckasLQAYcw++bC7B1z+Nc7YyrNPw== 
</ds:X509Certificate> 
</ds:X509Data> 
</ds:KeyInfo> 
</ds:Signature> 
<saml:Subject> 
<saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" 
NameQualifier="https://www.netiqtst.com/nidp/sam12/metadata" 
SPNameQualifier="urn: federation:MicrosoftOnline">bZM2NkBuZXRpcXRzdC5jb20=</ 
saml:NameID> 
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> 
<saml:SubjectConfirmationData InResponseTo="_3ae4edbc -7ab5 -48c7-a08e- 
b8d6e395e02c" NotOnorAfter="2012-09-09T09:41:51Z" Recipient="https:// 
login.microsoftonline.com/login.srf"/> 
</saml:SubjectConfirmation> 
</saml:Subject> 
<saml:Conditions NotBefore="2012-09-09T05:55:12Z" NotOnOrAfter="2012-09- 
09T11:28:30Z"> 
<saml:AudienceRestriction> 
<saml:Audience>urn: federation: MicrosoftOnline</saml : Audience> 
</saml:AudienceRestriction> 
</saml:Conditions> 
<saml:AuthnStatement AuthnInstant="2012-09-09T08:41:51Z" 
SessionIndex="idF5JcewGwWYwS3bOkmJS2wJuNqitU"> 
<saml:AuthnContext> 


<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</ 
saml:AuthnContextClassRef> 
<saml:AuthnContextDeclRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</ 
saml:AuthnContextDeclRef> 
</saml:AuthnContext> 
</saml:AuthnStatement> 
<saml:AttributeStatement> 
<saml:Attribute xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http:/ 
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/www .w3.org/2001/XMLSchema-instance" Name="IDPEmail" 
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 
<saml:AttributeValue xsi: type="xs:string">03662@netiqtst.com</ 
saml:AttributeValue> 
</saml:Attribute> 
<saml:Attribute xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http:/ 
/www .w3.org/2001/XMLSchema-instance" Name="ImmutableID" 
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> 
<saml:AttributeValue xsi:type="xs:string">bzM2NkBuZXRpcXRzdC5j b20=</ 
saml:AttributeValue> 
</saml:Attribute> 
</saml:AttributeStatement> 
</saml:Assertion> 
</samlp:Response> 


Sample WS-Trust Token 


<saml:Assertion AssertionID="nsts150b8594- Oaf f -424f -8113-46045d943171" 
IssueInstant="2014-05-09T07:00:18.019Z" Issuer="https://namnetiq.in/nidp/wsfed/" 
MajorVersion="1" MinorVersion="1" xmins:ds="http://www.w3.org/2000/09/xmldsig#" 
xmins:exci14n="http: //www.w3.org/2001/10/xml-exc-c14n#" 
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:xs="http://www.w3.org/ 
2001/XMLSchema"> 
<saml:Conditions NotBefore="2014-05-09T07:00:18.019Z" NotOnOrAfter="2014-05- 
O9TO7:06:18.019Z"> 
<saml:AudienceRestrictionCondition> 
<saml:Audience> 
urn: federation:MicrosoftOnline 
</saml:Audience> 
</saml:AudienceRestrictionCondition> 
</saml1:Conditions> 
<saml:Advice/> 
<saml:AuthenticationStatement AuthenticationInstant="2014-05-09T07:00:18.019Z" 
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"> 
<saml:Subject> 
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid- 
format:unspecified" NameQualifier="urn:federation:MicrosoftOnline"> 
TLP1AnEzZIcOEEtEyz9ZxMyA== 
</saml:NameIdentifier> 
<saml:SubjectConfirmation> 
<saml:ConfirmationMethod> 
urn:oasis:names:tc:SAML:1.0:cm: bearer 
</saml:ConfirmationMethod> 
</saml1:SubjectConfirmation> 
</saml:Subject> 
</saml1:AuthenticationStatement> 
<saml:AttributeStatement> 
<saml:Subject> 
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid- 
format:unspecified" NameQualifier="urn:federation:MicrosoftOnline"> 
TLP1inEzIcOEEtEyz9ZxMyA== 
</saml:NameIdentifier> 
<saml:SubjectConfirmation> 
<saml:ConfirmationMethod> 
urn:oasis:names:tc:SAML:1.0:cm: bearer 
</sam1:ConfirmationMethod> 
</saml:SubjectConfirmation> 
</saml:Subject> 
<saml:Attribute AttributeName="UPN" AttributeNamespace="http:// 
schemas .xmlsoap.org/claims"> 
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<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"> 
namtest@namnetiq.in 
</saml:AttributeValue> 
</saml:Attribute> 
<saml:Attribute AttributeName="ImmutableID" AttributeNamespace="http:// 
schemas .microsoft.com/LiveID/Federation/2008/05"> 
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"> 
TLP1inEzIcOEEtEyz9ZxMyA== 
</saml:AttributeValue> 
</saml:Attribute> 
</saml:AttributeStatement> 
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
<ds:SignedInfo> 
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml1-exc- 
c14n#"/> 
<ds:SignatureMethod Algorithm="http://www.w3.0rg/2000/09/xmldsig#rsa- 
sha1"/> 
<ds:Reference URI="#nsts150b8594- Oaff - 424f -8113-46045d943171"> 
<ds:Transforms> 
<ds:Transform Algorithm="http://www.w3.org/2000/09/ 
xmldsig#enveloped-signature"/> 
<ds:Transform Algorithm="http://www.w3.org/2001/10/xm1-exc-c14n#"/> 
</ds:Transforms> 
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#shai"/> 
<ds:DigestValue> 
OZVvO3DbVOQq7m9qg7ER4HO124bmA= 
</ds:DigestValue> 
</ds:Reference> 
</ds:SignedInfo> 
<ds:SignatureValue> 
SQWwAA39fFYb3VJPBebZ6bsiUhOC+8ElbgDv2yG6xq3WLYUX/DoQ6RLF sb/1mVmMQBcGqhUxhcDRAT 
k6JA3djHbZCrZh7qblc8uBr+nm1SzpS/B07todTLut+g835wGSKdpnpSoTjh0285Mj soomnrL+A4S 
33F5Ld50V0TPoar 1wpBPFOgm7k9SnzjUOh7yIpP7Y1ZX1uF2SPvNeDRhKNEI sWwSPUY 9mwO04An9V 
ASC1Cb1Q7+vEtCxggJ4A6nxk8G9bvPRisk 7H5FfTLiNFOTHNEZU5s6KnyGHCc6k2/ jJWHHF4Appg/aJ 
ZelyQR9OMKagNe60SAU2ZU83GM8WUst+03+PVI3A== 
</ds:SignatureValue> 
<ds:KeyInfo> 
<ds:X509Data> 
<ds:xX509Certificate> 


MIIFSTCCBDGgAWIBAgIGb+MI39nZMAOGCSqGSIb3DQEBCWUAMIHGMQswCQYDVQQGEWJVUZEQMA4G 
A1UECBMHQX Jpem9uYTETMBEGALUEBXMKU2NvVdHRZZGFSZTELMCMGALUEChMCU3RhcmZpZwxkIFR1L 
Y2hub2xvZ211cywgSw5jLjEZMDEGALUECXMqaHROcDovL2NlcnRZLnNOYXJmaWVSZHRLY2guY29t 
L3J1cG9zZaxXRvcnkvMTQwMgYDVQQDEyt TdGFyZm11bGQgU2Vj dXJLIENLcnRpZm1jYXRIIEF1dGhv 
cml0eSAt IECyMB4XDTEOMDUWN j ASMDYWNVOXDTELMDIyNj EyMDQWNFOowOTEhMB8GA1UECXMYRGOt 
YWLluIENvbnRyb2wgVmF saWRhdGVkMRQWEg YDVQQDEwtuYWLuZxXRpcS5pbjCCASIwDQY JKoZIhvcn 
AQEBBQADggEPADCCAQoCggEBAMzj EinlOiwzMpKBQO+H2sb+Hif rmVi7 JDZHRFOKJakG+nXsgVx2 
QRTONOUbVoeglDtaTZSKr FbOmc/E3aEkgSU67DAzZWvtm3nUSboJc4QVWQ1 JmxXIP989K2H1Das twE 
Srg6iwOMMUUz9ZadP3BQjV4VVB9qxX81D321D4TiigJYUDg5tpaUnftddiR+rZQROea3ABCO+o0eZa 
7w+jVFUOAP+uUG2iJ4zkSI0+F3wIXDNZMYQwF1TvnCT06/4cRW1xX0GxhOBbZGdYnOqHZAOu90kT2B 
gnz+aTaMGSIPpPr+PXxjB31XqeAhBRoxgrddwIt1Dawyr JETPOrzfMhd1i+QSXHCCAwEAAaOCAccw 
QgHDMAwGA1UdEWEB/wQCMAAWHQY DVRO1BBYWFAY IKwY BBQUHAWEGCCSGAQUFBwWMCMA4GA1UdDWEB 
/WQEAWIFODA7BgNVHR8ENDAyMDCgLgAshipodHRwO0i8vY3JSLnNOYXJmaWVSZHR1Y2guY29tL3Nm 
aWcyczEt0C5jcmwwwQYDVROgBFIWUDBOBgt ghkgBhviuAQcXATA/MDOGCCSGAQUFBwIBF j FodHRw 
0i8vY2VydGlmaWNhdGVZLnNOYXJmaWVSZHRLY2guY29tL3J1cG9zaxRvcnkvMIGCBggrBgEFBQcB 
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AQR2MHQwKgY I[KwYBBQUHMAGGHmhOdHA6L y9VY3NWLNNOYXJmaWVSZHRLY2guY29tLZBGBggr BgEF 
BQcwAoY6aHROcDovL2NlcnRpZm1jYXR1icy5zdGFyZm11bGROZWNoLmNvbS9yZXBvc210b3J5L3Nm 
awcyLmNydDAf BgNVHSMEGDAWgBQLRYFOUCY4PTStLL7Natm2PbNmY ZAnBgNVHREEIDAeggtuYwiu 
ZXRpcSSpboIPd3d3Lm5hbw51dG1xLmluMBOGALUdDgQWBBQANCLVLYFFU3cAkKVFQz/Txut tEUTAN 
BgkqhkiG9wOBAQsFAAOCAQEAySHcxqGpgrm9HSiSIFzDO0dC9BraZdjh+FfIUBeKRUBmSjSByPJIHj 
OGuBnY8FtuPY8/e1kKhzwhZcuUhY3zwvQzbWStWLraySJyO1SZRRJC4onLbx42ARdKbRgxA/JDsmY 
aTnyYqt+ZOLm6XUt DweFEDkklAy2s08gru540gJ0iD/ JyX/dgZEH/v91GjdNFUDwG4dLz++a201/U 
UfqJye7RO5UgNkewcG9Kj ydiTgP7Mv6m8/JjzZ0131ej] IVVqwz30fotagirrIWwG20gtkOJUFrY73 
COKTZSpPSZXMGN2FJpRSymt0+cqVLEUAK6/SCr 2mhBvxg4GJuxuzSLp2kSrIfA== 
</ds:X509Certificate> 
</ds:X509Data> 
</ds:KeyInfo> 

</ds:Signature> 

</saml:Assertion> 


Sample WS-Federation Token 


<wst:RequestedSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/ 
trust"> 
<saml:Assertion AssertionID="idjTptEEQd5CuKky - OM-MBCY91DHVQ" 
IssueInstant="2014-05-09T06:44:07Z" Issuer="https://namnetiq.in/nidp/wsfed/" 
MajorVersion="1" MinorVersion="1" 
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"> 
<saml:Conditions NotBefore="2014-05-09T06:29:07Z" NotOnOrAfter="2014-05- 
09T06:59:07Z"> 
<saml:AudienceRestrictionCondition> 
<saml:Audience> 
urn: federation:MicrosoftOnline 
</saml:Audience> 
</saml:AudienceRestrictionCondition> 
</saml:Conditions> 
<saml:AuthenticationStatement AuthenticationInstant="2014-05-09T06:44:07Z" 
AuthenticationMethod="name/password/uri"> 
<saml:Subject> 
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid- 
format: unspecified"> 
TLP1inEzIcOEEtEyz9ZxMyA== 
</saml:NameIdentifier> 
<saml:SubjectConfirmation> 
<saml:ConfirmationMethod> 
urn:oasis:names:tc:SAML:1.0:cm:bearer 
</saml:ConfirmationMethod> 
</saml:SubjectConfirmation> 
</saml:Subject> 
</saml:AuthenticationStatement> 
<saml:AttributeStatement> 
<saml:Subject> 
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid- 
format: unspecified"> 
TLP1AnEzZIcOEEtEyz9ZxMyA== 
</saml:NameIdentifier> 
<saml:SubjectConfirmation> 
<saml:ConfirmationMethod> 
urn:oasis:names:tc:SAML:1.0:cm:bearer 
</saml:ConfirmationMethod> 
</saml:SubjectConfirmation> 
</saml:Subject> 
<saml:Attribute AttributeName="UPN" AttributeNamespace="http:// 
schemas .xmlsoap.org/claims"> 
<saml:AttributeValue> 
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XX 
</saml:AttributeValue> 
</saml:Attribute> 
<saml:Attribute AttributeName="ImmutableID" AttributeNamespace="http:/ 
/schemas .microsoft.com/LiveID/Federation/2008/05"> 
<saml:AttributeValue> 
XX 
</saml:AttributeValue> 
</saml:Attribute> 
</saml:AttributeStatement> 
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
<ds:SignedInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml1- 
exc-c14n#" xmlns="http://www.w3.org/2000/09/xmldsig#"/> 
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/ 
xmldsig#rsa-shai" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"/> 
<ds:Reference URI="#idjTptEEQd5CuKy-OM-MBCY91DHVQ" xmins:ds="http:/ 
/www .W3.0rg/2000/09/xmldsig#"> 
<ds:Transforms xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
<ds:Transform Algorithm="http://www.w3.org/2000/09/ 
xmldsig#enveloped-signature" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"/> 
<ds:Transform Algorithm="http://www.w3.org/2001/10/xm1-exc- 
ci4n#" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"/> 
</ds:Transforms> 
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/ 
xmldsig#shai" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"/> 
<DigestValue xmlns="http://www.w3.org/2000/09/xmldsig#"> 
VOVgMA5UmoGFqXL4ENVYPSH/aPO= 
</DigestValue> 
</ds:Reference> 
</ds:SignedInfo> 
<SignatureValue xmlns="http://www.w3.org/2000/09/xmldsig#"> 


hwPIdSGG+M29sih+5MiwEf862d5K/ZSST3XVn1k IwWwN3HaLi/yAnGi0Uf6nZNJxE99pudE1Udy3R 
Kc5z8iQAu3gekVGANk4n2mDKZVet1kKEcgHGsfdwGxCkz5bpsPsaMB+pJyvFqu/RIRXIqsZtVrxv 
7PwOIwUPxJQesNhJrdoJNskxr65ckj2EeL5scCrDh9mYvtMCh/QaOC3ALXUm+hBFj 21hqwigQp58i 
m68DFTwh35pDkm4AXVxSRCm/9FKUOPGSXeU+0016GV/FISLiEmat+48dNOawlJvxzPI/cUayyJU2N 
3EZp7LpZLfFErushLBQQ9YmDNmevpCQoN4cZtuA== 


</SignatureValue> 
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
<ds:X509Data xmins:ds="http: //www.w3.org/2000/09/xmldsig#"> 
<ds:X509Certificate xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 


MIIFSTCCBDGgAWIBAgIGb+MI39nZMAOGCSqGSIb3DQEBCWUAMIHGMQswCQYDVQQGEWJVUZEQMA4G 
A1UECBMHQX Jpem9uYTETMBEGALUEBXMKU2NvVdHRZZGFSZTELMCMGALUEChMCU3RhcmZpZwxkIFR1 
Y2hub2xvZ211cywgSw5jLjEZMDEGALUECXMqaHROcDovL2NlcnRZLnNOYXJmaWVSZHRLY2guY29t 
L3J1cG9zZaXRvcnkvMTQwMgYDVQQDEyt TdGFyZm11bGQgU2Vj dXJLIENLcnRpZm1jYXRIIEF1dGhv 
cml0eSAt IECyMB4XDTEOMDUWN j ASMDYwWNVOXDTELMDIyNj EyMDQWNFOWwOTEhMB8GA1UECXMYRGOt 
YWLluIENvbnRyb2wgVmFsaWRhdGVkMRQWEgYDVQQDEwtuYWLuZxXRpcS5pbj CCASIwDQY JKoZIhvcNn 
AQEBBQADggEPADCCAQoCggEBAMzj EinlOiwzMpKBQO+H2sb+Hif rmVi7 JDZHRFOKJakG+nXxXsgVx2 
QRTONOUbvVoeglDtaTZSKr FbOmc/E3aEkgSU67DAzZWvtm3nUSboJc4QVWQ1 JmXIP989K2H1Das twE 
Srg6iwOMMUUz9ZadP3BQjV4VVB9qX81D321D4TiigJYUDg5tpaUnftddiR+rZQROea3ABCO+0eZa 
7w+jVFUOAP+UG2iJ4zkSI0+F3wIXDNZMYQwF1TvnCT06/4cRW1xX0GxhOBbZGdYnOqHZAOU90kKT2B 
gnz+aTaMGSIPpPr+PXxXjB31XqeAhBRoxgrddwIt1Dawyr JETPOrzfMhd1i+QSXHcCAwEAAaOCAccw 
QgHDMAwGA1UdEWwEB/wQCMAAWHQY DVRO1BBYWFAY IKwY BBQUHAWEGCCSGAQUFBWMCMA4GA1UdDwWEB 
/WQEAWIFODA7BgNVHR8ENDAyMDCgLgAshipodHRwO0i8vY3JSLnNOYXJmaWVSZHR1Y2guY29tL3Nm 
aWcyczEt0C5j cmwwwQYDVROgBF IWUDBOBgt ghkgBhv1uAQcXATA/MDOGCCSGAQUFBwIBF j FodHRw 
0i8vY2VydGlmaWNhdGVZLnNOYXJmaWVSZHRLY2guY29tL3J1cG9zaxRvcnkvMIGCBggrBgEFBQcB 
AQR2MHQwKgY I[KwYBBQUHMAGGHmhOdHA6L y9vVY3NwLNNOYXJmaWVSZHRLY2guY29tLZBGBggr BgEF 


Configuring Authentication 


5.3 


5.3.1 


5.3.1.1 


BQcwAoY6aHROcDovL2NlcnRpZm1jYXR1icy5zdGFyZm11bGROZWNoLmNvbS9yZXBvc210b3J5L3Nm 
awcyLmNydDAfBgNVHSMEGDAWgBQLRYFOUCY4PTStLL7Natm2PbNmYZAnBgNVHREEIDAeggtuYwiu 
ZXRpcSSpboIPd3d3Lm5hbw51dG1xLmluMBOGALUdDgQWBBQANCLVLYFFU3cAkKVvFQz/Txut tEUTAN 
BgkqhkiG9wOBAQsFAAOCAQEAySHcxqGpgrm9HSiSIFzDO0dC9BraZdjh+FfIUBeKRUBmSjSByPJIHj 
OGuBnY8FtuPY8/e1kKhzwhZcuUhY3zwVQzbWStWLraySJyO1SZRRJC4onLbx42ARdKbRgxA/JDsmY 
aTnyYqt+ZOLm6XUt DweFEDkklAy2s08gru540gJ0iD/ JyX/dgZEH/v91GjdNFUDwG4dLz++a201/U 
UfqJye7Rb5UgNkewcG9Kj ydiTgP7Mv6m8/Jjz0131ej] IVVqwz30fotagirrIWwG20gtkOJUFrY73 
COKTZSpPSZxXMGN2FJpRSymt0+cqVLEUAK6/SCr 2mhBvxg4GJuxuzSLp2kSrIfA== 


</ds:X509Certificate> 
</ds:X509Data> 
</ds:KeyInfo> 
</ds:Signature> 
</saml:Assertion> 
</wst :RequestedSecurityToken> 


Advanced Authentication 


This section discusses the following advanced authentication techniques that are currently supported 
by Access Manager: 
¢ Section 5.3.1, “Two-Factor Authentication Using Time-Based One-Time Password,” on page 645 
¢ Section 5.3.2, “RADIUS Authentication,” on page 647 
¢ Section 5.3.3, “NetIQ Advanced Authentication,” on page 648 


Two-Factor Authentication Using Time-Based One-Time 
Password 


This section explains how to use Time-Based One-Time Password (TOTP) as a second 
authentication factor with Access Manager. TOTP uses a six-digit number (OTP) in addition to first 
authentication (for example: username, password) to log in to protected services. 


The first step is to register the TOTP client with the secret key. This secret key is used for all future 
login to the website. 


Typically, users download and install the TOTP app on their devices. To log in to a website or service 
that uses two-factor authentication, in addition to the user name and password, the users enter an 
OTP generated by the TOTP app. Access Manager validates the OTP and authenticates the user. 

¢ Section 5.3.1.1, “Why Two-Factor Authentication,” on page 645 

¢ Section 5.3.1.2, “Prerequisite,” on page 646 

¢ Section 5.3.1.3, “Configuring TOTP Class, Method, and Contract,” on page 646 

¢ Section 5.3.1.4, “Registering with TOTP,” on page 647 

¢ Section 5.3.1.5, “Verifying TOTP Configuration,” on page 647 


Why Two-Factor Authentication 
Two-factor authentication such as TOTP provides additional security for the systems. It works on the 
principle of granting access based on a knowledge factor (something the user has) and a possession 


factor (something the user knows). This helps organizations to implement a multi-factor 
authentication scheme to satisfy regulatory requirements or increase security. 
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5.3.1.2 


+ 


+ 


5.3.1.3 
1 
2 
3 
4 
5 
6 
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Prerequisite 


Download and install the TOTP app on your device. This app generates an OTP that is later 
used for authentication. 


TOTP relies on the device time to generate an OTP. So, it is important that the time on your 
device is accurate. 


Configuring TOTP Class, Method, and Contract 


Log in to Administration Console. 
Click Devices > Identity Servers > Edit > Local > Classes > New to add a new class. 
Specify a name to identify the class. 


Select TOTPClass from the Java Class option. The Java class path is displayed as 
com.novell.nidp.authentication.local.TOTPAuthenticationClass. 


Click Apply. By default, the TOTP class stores the secret key in the Shared Secret store and no 
further configuration is required. 


[Optional] You can also store the secret key in an LDAP attribute, file, or memory. Perform the 
following steps: 


NOTE: File and Memory class implementation are not recommended for production deployment 
and are only suitable for a single node Identity Server test environment. 


LDAP user attribute: This option stores the secret key on an LDAP attribute of the user object 
in the user store. 


1. Select the Properties tab of the TOTP class configuration. Add a new property to indicate 
that the secret key must be stored in an LDAP attribute of the user object in the user store. 


Specify the Property Name as SECRET_STORE_CLASS and Property Value as USERSTORE. 
2. Add another property to indicate the attribute in which the secret key must be stored. 


Specify the Property Name as SECRET_LDAP_ATTRIBUTE_NAME and specify the name of any 
single-valued attribute. For example, you can specify the Property Value as mobile, 
costcentre etc. 


The secret key is encrypted and stored in the LDAP attribute. If you do not specify any 
Property Value, the secret key is stored in the carLicense LDAP attribute. 


NOTE: Do not use a multi-valued LDAP attribute like email address as the Property Value 
as the user registration will fail. It is also important to ensure that the LDAP attribute you 
have specified as the Property Value is a non-operational attribute. For example, it is not 
recommended to use LDAP Attributes like groupmembership. 


File class: The File class writes the secret key to a file on Identity Server file system. 


1. Select the Properties tab of the TOTP class configuration and add a new property to have 
the user's secret key stored in a file on the file system. 


2. Specify the Property Name as SECRET_STORE_CLASS and Property Value as FILE. 


Memory class: The Memory based class writes the secret key into memory. This memory is 
transient in nature and therefore the secret key value is lost each time Identity Server is 
restarted. 


1. Select the Properties tab of the TOTP class configuration and add a new property to define 
the memory-based property where each user’s secret key is stored. 


2. Specify the Property Name as SECRET_STORE_CLASS and Property Value as MEMORY. 
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7 Click Devices > Identity Servers > Edit > Local > Methods. Select New to add a new method. 


8 Specify a name to identify the method. Select the TOTP class from the list. This links the TOTP 
class to the authentication method. 


9 Deselect the Identifies User option. Click Apply to save the changes. 
10 Select the user store from the list of Available user stores and move it to User store. 


11 You can either use an existing authentication contract or create a new authentication contract. 
For example, you can add the default Name/Password - Form method as the first method and 
TOTP method as the second method. Click Apply to save the changes. 


NOTE: If you use TOTP as a post-authentication method in a federation setup, a JSP file not 
found message is displayed and federation fails. 


5.3.1.4 Registering with TOTP 


1 Go to Access Manager Identity Server page http(s)://<idp server >:<port>/nidp 


2 Select the contract where TOTP is configured as the second method for two-factor 
authentication. 


3 Login with the first method. 


4 Click the link beside Please register for two factor authentication to generate a OTP. Make a 
note of the secret key displayed. 


If you have installed the TOTP client on your device, scan the code. You can also manually enter 
the secret key in the TOTP mobile client. 


After the registration is complete on the TOTP client on your mobile, the OTP is displayed. 


5.3.1.5 Verifying TOTP Configuration 


1 Go to Access Manager Identity Server page: http(s)://<idp server >:<port>/nidp 


2 Select the contract where TOTP is configured as the second method for two-factor 
authentication. 


3 Login with the first method. 


After successfully authenticating with the username and password, prompt is displayed to enter 
the TOTP OTP. 


4 Use the TOTP app to generate the OTP and log in by using this OTP. 


5.3.2 RADIUS Authentication 


RADIUS enables communication between remote access servers and a central server. Secure token 
authentication through RADIUS is possible because Access Manager works with Novell Modular 
Authentication Service (NMAS) RADIUS software. Access Manager supports both PIN and 
challenge-and-response methods of token-based authentication. In other words, RADIUS represents 
token-based authentication methods used to authenticate a user, based on something the user 
possesses (for example, a token card). Token challenge-response is supported for two-step 
processes that are necessary to authenticate a user. 


1 Click Devices > Identity Server > Edit > Local > Classes. 
2 Click New. 
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5.3.3 


3 Specify a display name, then select RadiusClass or ProtectedRadiusClass from the drop-down 


menu. 


4 Click Next. 
5 Click New to add an IP address for the RADIUS server. You can add additional servers for 


failover purposes. 


6 Click OK. 


7 


Fill in the following fields: 

Port: The port of the RADIUS server. 

Shared Secret: The RADIUS shared secret. 

Reply Time: The total time to wait for a reply in milliseconds 

Resend Time: The time to wait in milliseconds between requests. 

Server Failure Retry: The time in milliseconds that must elapse before a failed server is retried. 


JSP: Specify the name of the login page if you want to use something other than the default 
page. The filename must be specified without the JSP extension. The default page is used if 
nothing is specified. 


User Look Attribute Name: Specify the LDAP attribute on which the user will be searched in 
the Radius server. CN is the default attribute. 


Require Password: Select to require the user to also specify an LDAP password. 


8 Click Finish. 
9 Create a method for this class. 


10 


11 


+ 


For instructions, see Section 5.1.3, “Configuring Authentication Methods,” on page 377. 
Create a contract for the method: 
For instructions, see Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


If you want the user’s credentials available for Identity Injection policies and you did not enable 
the Require Password option, add the password fetch method as a second method to the 
contract. For more information about this class and method, see Section 5.1.11, “Password 
Retrieval,” on page 406. 


Update Identity Server. 


NetlQ Advanced Authentication 


NetIQ Advanced Authentication Access Manager plug-in now comes bundled with Access Manager. 
Using Advanced Authentication methods, you can configure multi-factor authentication with Access 
Manager. 


The following are supported Advanced Authentication classes: 


Dynamic Class: This authenticating class sends a list of chains from which the user can select a 
chain and authenticate. Only the chains which are enrolled in the Advanced Authentication portal 
will be available to the user for authentication. 


NOTE: Fingerprint and PKI methods can be configured using Dynamic Class only. There are no 
separate classes for Fingerprint and PKI methods. 


Email Class: This authentication class sends an email to user’s registered email address with 
an OTP that is valid for a specified time. You can use this OTP to authenticate within a certain 
time frame. 
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¢ Emergency Password Class: This authentication class authenticates users with a temporary 
password. 


¢ FIDO U2F Class: This authentication class authenticates users with the help of a U2F security 
key. 


IMPORTANT: FIDO U2F will not work if enrollment and authentication are performed on different 
domain names. With Access Manager and Advanced Authentication, you will certainly have two 
domain names, one for Identity server and another for Advanced Authentication server. To 
workaround this you should proxy the Identity server and Advanced Authentication server under 
the same domain name. Perform the following steps to configure FIDO U2F class: 


1. Create a path-based, multi-homing proxy service with Advanced Authentication server as 
the web server. Create five paths under the proxy service with the URL paths as follows: 


+ /account, /admin, /api, /auth, and /static 
The published DNS name must be identical to the Identity Server domain name. 


2. Create another path-based, multi-homing proxy service with Identity server as the web 
server and Advanced Authentication server as the parent server. Create a path under the 
proxy service with the URL path as follows: 


è /nidp 


3. Configure a protected resource to the proxy services with URL paths as /account/*, / 
admin/*, /api/*, /auth/* and /static/* and Advanced Authentication server as the web 
server. You do not need to associate the protected resource with any contract. Configure 
another protected resource to the proxy service with URL path as /nidp/* and Identity 
server as the web server. 


For more information, see Configuring FIDO U2F class. 


¢ Fingerprint Class: This authentication class authenticates using a fingerprint scanner. 


+ HOTP Class: This authentication class is an event-based OTP authentication. There is no time 
frame for a HOTP. 


+ Password (PIN) Class: This authentication class stores a password in the Advanced 
Authentication appliance - that is not connected to your corporate directory. This can be a PIN or 
a simple password. 


¢ RADIUS Class: This authentication class forwards user’s authentication request to a third-party 
Radius server. 


¢ Security Question Class: This authentication class allows users to enroll answers to an 
administrator-defined number of security questions. When you authenticate by using security 
questions, Advanced Authentication asks you all the security questions or a subset of the 
security questions. 


¢ Smartcard Class: This authentication class allows users to authenticate by using a smart card. 
¢ Smartphone Class: This authentication class allows you to authenticate by using a smartphone. 


¢ SMS Class: This authentication class sends an SMS to user’s registered mobile number, 
containing OTP. User can use this OTP to authenticate within a certain time frame. 


+ TOTP Class: This authentication class is a time-based OTP authentication. This method uses a 
predefined time step, which is set to 30 seconds by default. 


+ 


Voice Call Class: This authentication class makes a phone call on user’s registered mobile 
requesting to provide a pre-defined PIN. 
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Optional Properties 


In addition to the existing classes, Access Manager also supports the following optional properties 
(KEY/Value) for authentication methods: 


+ 


+ 


+ 


Repository Name: REPONAME. The name of the repository used for Advanced Authentication. 
This parameter may not be used if the default repository is selected in the Login options policy 
of Advanced Authentication server appliance. 


Configuration File: CONFIGFILE. The name of the configuration file path. This parameter is used 
only if the configuration file has a different location. The default configuration file location is: / 
etc/aaplugin/config.xml. 


Timeout Value: RECHECKTIMEOUT. The time out parameter that is used to prevent loops. The 
default value is 300 seconds. The following are minimum recommended values: 


+ Email: 120 seconds 

+ FIDO U2F: 30 seconds 

+ HOTP: 30 seconds 

+ RADIUS: 30 seconds 

¢ Security Question: 30 seconds 
+ Smartcard: 30 seconds 

¢ Smartphone: 60 seconds 

+ SMS: 30 seconds 

+ TOTP: 30 seconds 

+ Voice Call: 30-60 seconds 


Error Info JSP Page: ERRORJSP. The name of the JSP page that stores the error logs. This is 
for critical errors and failures related to the authentication process. The default file is 
PluginErrorPage. jsp. The file is located at: 


+ Linux: /opt/novell/nids/lib/webapp/jsp 
+ Windows: $INSTALL_PATH\Tomcat \webapps\nidp\jsp 


LDAP Authentication Page: LDAPJSP. The name of the LDAP authentication page. This 
parameter is used for customization. It allows you to customize the LDAP login page for each 
method. The default file is LdapAuth. jsp, The file is located at: 


+ Linux: /opt/novell/nids/lib/webapp/jsp 
+ Windows: $INSTALL_PATH\Tomcat \webapps\nidp\jsp 


Method Page: METHODJSP: The name of the method page. This parameter is used for 
customization. It allows you to customize the Method page for each method. The default file is 
<MethodName>Auth. jsp. The file is located at: 


+ Linux: /opt/novell/nids/lib/webapp/jsp 
+ Windows: $INSTALL_PATH\Tomcat \webapps\nidp\jsp 


LDAP Password Sync Page: LDAPSYNCJSP. The name of the LDAP password synchronization 
page. The default file is LDAPSyncPage. jsp. The file is located at: 


+ Linux: /opt/novell/nids/lib/webapp/jsp 
+ Windows: $INSTALL_PATH\Tomcat \webapps\nidp\jsp 


Max Password Length: PWDMAXLENGTH. This parameter restricts the maximum length of a 
password. The default value is 100 characters. This parameter can be used only for YubiKey 
tokens (FIDO U2F class) 
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5.3.3.2 


+ Advanced Authentication Enrollment URL: ENROLLURL. This parameter contains the URL of 
the Advanced Authentication Self-Service Portal. The default value is https:// 
<NetIQAdvancedAuthenticationFramework_server_address>:<server_port>/account. 


¢ DEBUG: This parameter gathers additional information from a log file. It adds data from the 
server requests and server responses to the log file. To enable debug logging, set the value to 1. 


+ LOGFILE: This parameter contains the path of the plug-in log file. It allows you to save the log file 
in a different location. For example, specify the file path /tmp/NAMAAplugin. log in the value 
field. 


Prerequisites 


The following list includes prerequisites required for using NetIQ Advanced Authentication: 


NOTE: The following list is applicable only on a fresh installation of Access Manager 4.3. If you 
upgrade Access Manager to 4.3, you can skip the first two points. 


¢ You must first configure Advanced Authentication Server 5.3 or above. To configure the server, 
see Advanced Authentication Server Appliance Deployment. 


+ After configuring the server, end users must enroll to Advanced Authentication Self-Service 
portal. To enroll, see Authentication Methods Enrollment. 


¢ Specify the server details. See Section 3.5.9, “Specifying Advanced Authentication Server 
Details,” on page 105. 


Configuring Advanced Authentication 


To configure Advanced Authentication, perform the following steps: 


1 Click Devices > Identity Servers > Edit > Local > Classes. 

2 Select New and specify a name to identify the class. 

3 Select a class under Advanced Authentication from the Java Class drop-down list. 

4 Click Next > OK > Finish. 

5 Create a method for this class. You can create a method by using one of the following options: 


¢ Identifies User: Adds only a desired Advanced Authentication method from the available 
list. Selects Identifies User. 


For example: If the Email contract is configured to use only the Email method, you must 
configure both Password & Email (two-factor) and Email (one-factor) chains in the Chains 
section (the two-factor chain must be higher than an appropriate one-factor chain). Enable 
them in the Access Manager event of the Advanced Authentication Administrative Portal. 


¢ Identifies User: Adds any standard method as a first-factor from the available list and a 
desired Advanced Authentication method as the second-factor. 


For example: If Email contract is configured to use as a combination of a standard method 
and an Email method, you must configure and enable only Email (one-factor) chain. 


For more information, see Section 5.1.3, “Configuring Authentication Methods,” on page 377. 
6 Create a contract for the method. 
For instructions, see Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


Configuring Authentication 651 


5.4 


5.4.1 


If you want the user’s credentials available for Identity Injection policies and you did not select 
Require Password, add the password fetch method as a second method to the contract. For 
more information about this class and method, see Section 5.1.11, “Password Retrieval,” on 
page 406. 


7 Update Identity Server. 


Social Authentication 


Access Manager can be configured to support authentication through external OAuth providers like 
Facebook, Google+, Twitter, LinkedIn, and so on. Social authentication simplifies login for end users 
and does not require maintaining large user stores. This authentication can be configured using the 
SocialAuthClass. Login using social identities provide a convenient way for users, improving 
customer satisfaction and increased registration levels. For more information on how to configure the 
supported social authentication providers for API Keys and API Secrets, see Appendix 5.4.6, 
“Configuring Supported Social Authentication Providers for API Keys and API Secrets,” on page 656. 


Social login allows business, universities and government entities to leverage social identity providers 
to share select identity information for authentication via OAuth tokens. This information can then be 
used to provide protected online services ranging from customer-focused applications, university 
sites to state and local services and more. 


Use Case 


Authentication through external OAuth providers can be useful in the following two scenarios: 
¢ Allow external users to access secure resource 


For example, you may want your customers and partners to access https://forums.novell.com. 
Creating and managing these external users is a hassle for you and the user. Social 
Authentication helps in this scenario. 


Users will be allowed to sign in with their Facebook or Yahoo ID. Social authentication provider 
will give Access Manager a set of logged-in user’s attributes. Hence, you will get user data 
without maintaining it. Access Manager can use this user data and perform actions based on that 
if required. 


+ Apply policies to restrict users to access a protected resource 


If the Identify User Locally option is selected, the social provider user will be mapped to the local 
user and you can execute authorization policies based on the user attributes. For example, if Joe 
is a Facebook user, you can match the attributes of Joe in the local user store based on a rule 
and execute an authorization policy to access a protected resource. You want to apply policies 
on an incoming user. For example, your enterprise user 'Bob' has logged into https: // 

forums .novell.com/with a social identity. You may want to identify that 'Bob' is your local user 
and provide him with forum moderator privileges. The Identify User Locally option lets you map 
a social user to your local user and apply appropriate policies. 


¢ Simplify user login: You may want to keep the user in your user stores but still make the 
registration process easy for the users. Social authentication saves the user from remembering 
another identity. User can login with their social identity while the Auto Provision User option will 
map the incoming user specified attribute with an existing user in the local user store. If the 
attribute matches, user will be provisioned, else user will be prompted for local user 
authentication. 
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¢ Personalized web content in B2C scenarios: Organizations want to make services and 
information available in a manner that is personalized to individual. The common approach of 
creating individual identities for users is costly for the organization and inconvenient for the user. 
Social login allow users to login with their preferred form of identities. This simplifies the login 
experience for customers while increasing the registration levels and lowering IT costs. 

¢ Step up authentication: While you as an administrator want to improve the user registration 
through social identities, you would also want to ensure that a second factor authentication is 
employed when users access sensitive information. Access Manager provides options to 
configure multiple contracts for protected resources and as users access these resources, they 
can be prompted to login with a second factor such as their corporate identity or an OTP. 


5.4.2 Prerequisite 


You must have registered Access Manager with the social authentication providers and must have 
the API keys and API secrets for establishing federation between Access Manager and the provider 
for example, Facebook. 


5.4.3 Configuring SocialAuthClass 


Use Administration Console to define a new Social Authenticator class, method and contract for 
Identity Server cluster. Social authenticator providers such as Facebook, Google+, LinkedIn, and 
Twitter are supported. 


1 Log in to Administration Console. 

2 Click Devices > Identity Servers > Edit > Local > Classes. Select New to add a new class. 
3 Specify a name to identify the class. For example, Social authenticator. 

4 Select SocialAuthClass from the Java Class drop-down list. Click Next. 


5 Configure the User Identification settings if you need to perform actions on the logged in user. 
This is optional. By default, user authentication is done without mapping the social provider user 
to a local user. 


¢ Identify User Locally: Select this option to map the incoming user to an existing user in 
your user store. You can apply an authorization policy for these incoming users to provide 
access control. The following two parameters specify how to perform the user mapping: 


+ Local User LDAP Attribute: Select an attribute from the drop-down list, for example 
LDAP Attribute:mai! [LDAP Attribute Profile]. The incoming configured attribute from 
the social website is mapped to local user’s LDAP attribute. 


NOTE: If there are more than one social authentication providers configured, the Local 
User LDAP attribute must be a multi-valued attribute. This is required to store the social 
attributes corresponding to each social provider. 


¢ Social User Attribute: Select an attribute which provides a unique user identity for 
example Email. The user email provided in a social website will be mapped to the 
specified local user’s LDAP attribute. 


User mapping is done if the value of Local User Attribute is equal to the value of Social 
User Attribute. 
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NOTE: Provisioning will not occur in the following scenarios: 


+ If you are going to use Facebook or Google+ as your authentication provider, do 
not select DisplayName as Social User Attribute as these providers do not have 
the DisplayName attribute. 


+ If Social User Attribute is email attribute in Twitter. 


+ Auto Provision User: If you enable this option, incoming user specified attribute will be 
mapped with an existing user in the local user store. If the attribute matches, user will be 
provisioned, else user will be prompted for local user authentication. After authentication, 
user attribute will be mapped and stored. 


6 Click Add under Social Auth Providers to provide the authentication provider details. 


+ Auth Provider: Select the authentication provider from the drop-down list for example, 
Facebook. You can select from one of the predefined providers or select Other to specify 
your own providers. Note that only the predefined providers have been verified for 
compatibility with Access Manger. If you select Other, you must provide two additional 
information: 


+ Provider Name: Specify the name of the provider. Other provider names can be 
specified under Others option. Other provider name can be Yahoo, Hotmail, 
SalesForce, AOL, FourSquare, MySpace, Instagram, Mendeley or Yammer. Name of 
social authentication provider is case-sensitive and must match as listed. Else, social 
authentication class will not work. 


+ (Optional) Implementation Class: Specify a back end class that can authenticate with 
these providers if the other providers are not supported. This is needed only for a 
custom provider that is not in the list provided above. 


+ Consumer Key: Specify the API key that you received when you registered Access 
Manager with the Social authentication provider. 


+ Consumer Secret: Specify the secret that you received when you registered Access 
Manager with the Social authentication provider. 


7 Click OK and Finish. 
8 Continue with creating a contract and method for this class. 


NOTE: With the latest Facebook API, the user's email address is no longer shared by default. 
For social authentication with Facebook in Access Manager, configure the following properties in 
the Social Auth method: 


graph. facebook.com.custom_permissions = email 


For configuration information, see Section 5.1.3, “Configuring Authentication Methods,” on 
page 377 and Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


How Social Authentication Works With Access Manager 


For completing social authentication, Identity Server maps the social attribute value in token to the 
local user attribute value. The local attribute must be set in the following format for the matching to 
succeed. 


<socialprovidername>:<social attribute value> 
For example, consider that the social authentication class properties are set as follows: 


¢ Identify User Locally: Enabled 
¢ Local User LDAP attribute: Ldap Attribute:mail 
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¢ Social User Attribute: Email 

+ Auto Provision User: Enabled 

¢ Social Auth Provider: Facebook 
As the Auto Provision User setting is enabled, after authentication in Facebook, user is asked for a 
one-time local login. During this process, this user's mail attribute is updated with the social attribute 


value as facebook :<social-email-address>. Subsequent logins from the same user will be 
seamless and user will be identified automatically. 


If Auto Provision User setting is disabled, for the authentication to succeed, Access Manager will 
check if local user LDAP attribute mail value is facebook: <social-email-address>. 


NOTE: The attribute value is set with the provider's name. 


5.4.4 Adding Images for Social Authentication Providers 


You can add images for social authentication providers such as Facebook, LinkedIn, Twitter, Google+ 
and so on. For more information about adding images, see Section 3.5.5, “Adding Authentication 
Card Images,” on page 86. 
1 Click Devices > Identity Servers > Shared Settings > Authentication Card Images. 
2 Click New. 
3 Fill in the following fields. 
Name: Specify a name for the image. 
Description: Describe the image and its purpose. 
File: Click Browse, locate the image file, then click Open. 


Locale: From the drop-down menu, select the language for the card or select All Locales if the 
card can be used with all languages. 


4 Click OK. 


5 If you did not specify All Locales for the Locale, continue with Section 3.5.6, “Creating an Image 
Set,” on page 86. 


6 Add all the required images and click Close. 


After configuring Identity Server with the required social authentication provider images, the login 
page will display those images on the login page. You can select an image and access the social 
providers you have added when you access Identity Server URL. 


5.4.5 Changing the Social Authentication Icons 


The following procedure allows you to change the default icons of social authentication providers. 
1 Go to socialauth_icons. jsp file located at /opt/novell/nids/lib/webapp/jsp/. You can 
see all the supported providers and their corresponding public URL locations. 


2 To change the icon of a particular provider, go to the icon variable name of that provider and 
replace the existing URL location with required URL location. 


You can similarly change for other icons defined in the jsp file. 
3 Restart Identity Server after changing the jsp file. 
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5.4.6 


5.4.6.1 


Configuring Supported Social Authentication Providers for 
API Keys and API Secrets 


Access Manager requires API Keys and API Secrets from the supported social authentication 
providers to integrate with these providers. Follow the steps to configure the supported applications 
and to get keys from the social authentication providers. You can integrate with Facebook, LinkedIn, 
Twitter, and Google+. For other providers, see “Configuring SocialAuthClass” on page 653. 


NOTE: The procedures documented below may not match the Social Networking Providers’ interface 
when you create an application. If there are any changes, follow the wizard accordingly. The 
procedure below is for reference purpose and can vary based on provider configuration page. 


Integrating Access Manager with Facebook 


The following procedure enables you to generate API Key and API Secret with Facebook. 


1 Create a Facebook application for community. 
1a Log in to Facebook to access the Application (https://developers.facebook.com/apps) page. 
1b From the top right corner, click Add a New App. 
1c Select the platform Website. 
1d Click Skip and Create App ID. 
1e Fill in the following fields in the Create a New App ID screen: 
¢ Display Name: Specify a name for web application. 
¢ Contact Email: Specify the Email Address. 
+ Category: Select a category from the drop-down list. 
1f Click Create App ID. 


1g Inthe Security Check page key in the displayed Captcha text in the Text in the box field, 
then click Submit. 


The product setup page appears. 
1h Click Facebook Login > Get Started. 


+ Valid OAuth redirect URIs: Specify the IDP redirect URI. For example: https: //<IDP 
URL>:<Port Number>/nidp/jsp/socialauth_return.jsp. 


¢ Deauthorise Callback URL: Specify the IDP URI. For example: https: //<IDP 
URL>:<Port Number>/nidp/app. 


1i 
1j Navigate to the Dashboard page. 


Click Save Changes. 


The Dashboard page displays App Name, App ID and App Secret (hidden). 
1k Click Show to display the App Secret. 
1 


Copy the values of App ID and App Secret parameters. You will need these values when 
you configure Facebook with Access Manager. 


1m Click Settings on the left. In the Basic tab, review the details. 
1n Click Advanced tab and review the details. 


1o Click App Review, enable Make DemoApp public, then select Confirm to make this 
application and all its live features available. By default, it is selected as No. 
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1p Navigate to the Dashboard page 


The application status changes to Green and is online. 


2 Configure Facebook application Configuration Setting in Access Manager. The App ID and App 
Secret is used by Access Manager to configure Facebook. 


5.4.6.2 Integrating Access Manager with LinkedIn 


The following procedure enables you to generate API Key and API Secret with LinkedIn. 


1 Create a LinkedIn application. 


1a Log in to LinkedIn to access the application page: Linkedin (https://www.linkedin.com/ 
developer/apps). 


1b Click Create Application. 


1c Select the existing Company Name from drop-down or create a new Company Name. 


1d Fill in the following fields in the Create a New Application screen: 


+ 


+ 


+ 


+ 


+ 


Company Name: Specify the name of the company. 

Name: Specify the name of the application. 

Description: Specify a description of the application. 
Application Logo: Upload an image for the application. 
Application Use: Select a category from the drop-down list. 
Website URL: Specify a URL or nidp URL. 

Business Email: Specify your business email address. 
Business Phone: Specify your business phone number. 
Accept the agreement, then click Submit. 


1e Copy the value of Client ID and Client Secret parameters. These values will be required 
when you configure Linkedin providers with Access Manager. 


2 Configure Linkedin application Configuration Setting in Access Manager. The App ID and App 
Secret will be used by Access Manager to configure Linkedin. 


5.4.6.3 Integrating Access Manager with Twitter 


The following procedure enables you to generate API Key and API Secret with Twitter. 


1 Create a Twitter application. 


1a Log in to Twitter to access the Application (https://apps.twitter.com) page. 


1b From the drop-down box on the right, click Create New App. 


1c Fill in the following fields in the Create an Application page: 


+ 


+ 


+ 


+ 


Name: Specify a name for web application. 
Description: Specify a description for web application. 
Website: Specify the application url. 


Callback URL: Specify IDP redirect URI. For example: https://<IDP URL>:<Port 
Number>/nidp/jsp/socialauth_return.jsp 


1d Accept licence and click Create your Twitter Application. 


The App name, description, consumer key, and the callback url are displayed. 
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1e Goto Keys and Access Tokens tab and make a note of the Consumer Key and Consumer 
Secret. 


You will need these values when you configure Twitter with Access Manager. 
1f Click Create my access token to authorize application to access account. 


2 Configure Twitter application Configuration Setting in Access Manager. Access Manager uses 
the App ID and APP secret to configure Twitter. 


Integrating Access Manager with Google+ 


The following procedure enables you to generate API Key and API Secret with Twitter. 


1 Create a Google+ application. 


1a Log in to Google to access the Application (https://console.developers.google.com/apis/ 
library (https://console.developers.google.com/apis/library). 


1b Click Credentials on left, then create a project with a Project name. 
1c In the APIs Credentials popup, click Create credentials, then select OAuth client ID. 
1d Click Configure consent screen to set a product name on the consent screen. 
le Specify a product name and click save. 
The remaining fields are optional. The Email address is auto-populated. 

1f In Create client ID page, specify the following: 

+ Application type: Select Web application as the Application type. 

+ Name: Specify a name for web application. 

+ Authorized JavaScript origins: This is an Optional field. 


+ Authorized redirect URIs: Specify IDP redirect URI. For example: https: //<IDP 
URL>:<Port Number>/nidp/jsp/socialauth_return.jsp. 


1g Copy Oauth client ID and secret. 
These values are required when you configure Google+ with Access Manager. 


2 Configure Google+ application Configuration Setting in Access Manager. Access Manager uses 
the App ID and App secret to configure Google+. 


Risk-based Authentication 


Traditional password-based authentication systems have their own limitations at implementing 
security in an organization. Enhancing the strength of the password is inadequate to prevent security 
threats. Thus, there is a need to explore and apply better authentication techniques such as risk- 
based authentication. 


Risk-based authentication provides context-aware access control that acts to balance the level of 
trust against risk. It enables organizations to address access-related risks and improves user 

experience. Risk-based authentication enables to validate the risk of an access request at the run 
time and take appropriate actions such as forcing an advanced authentication or denying access. 


You can also assess risk in a federated setup with service providers such as Salesforce.com, SAP 
HR, and Oracle Financial with protocols such as SAML and WS Fed. 


Access Gateway can also control access for a protected resource based on the risk score. 
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The following illustration depicts risk-based authentication process: 
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The following illustration depicts the risk-based authentication in a federated setup: 
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This section describes risk-based authentication concepts and how to configure it. 


¢ Section 5.5.1, “How Risk-based Authentication Works,” on page 660 

¢ Section 5.5.2, “Why Risk-based Authentication,” on page 662 

¢ Section 5.5.3, “Features of Risk-based Authentication,” on page 663 

¢ Section 5.5.4, “Key Terms,” on page 668 

¢ Section 5.5.5, “Understanding Risk-based Authentication through Scenarios,” on page 669 
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¢ Section 5.5.6, “Understanding Risk Score Calculation,” on page 676 

¢ Section 5.5.7, “Configuring Risk-based Authentication,” on page 678 

¢ Section 5.5.8, “Enabling Auditing for Risk-Based Authentication Events,” on page 678 
¢ Section 5.5.9, “Configuring an External Database to Store User History,” on page 679 
¢ Section 5.5.10, “Enabling Logging for Risk-Based Authentication,” on page 680 

¢ Section 5.5.11, “Troubleshooting Risk Rule Configuration,” on page 680 


How Risk-based Authentication Works 


You can configure risk-based authentication in the following two ways: 


e Risk assessment and risk mitigation before authenticating a login attempt 
¢ Risk assessment and risk mitigation after authenticating a login attempt 


Risk Assessment and Risk Mitigation before Authenticating a Login Attempt 


You can assess the potential risk of a particular login attempt before authenticating the user and then 
mitigate the risk, if required. You can also configure specific authentication mechanisms based on the 
risk. In this scenario, user profile is not involved. In this scenario, risk-based authentication works by 
developing a risk score based on the following parameters: 

+ IP Address 

+ Cookie 

+ HTTP Header 

¢ Geolocation 

+ External parameters 

¢ Time of login 

¢ Device Fingerprint (without user attributes) 

+ Custom rule (without user attributes) 
This risk score is then evaluated against defined risk levels. You can define the risk levels based on 
the sensitivity of the information. After the risk level is identified, the authentication mechanism is 


selected and the user is authenticated. In cases of high risk, the user is either denied access or is 
required to go through additional authentication methods. 


NOTE: You cannot record history in this configuration because there are no user-context. If you want 
to use history with pre-authentication risk assessment, you must configure a post risk-based 
authentication. 


For example, an employee trying to log into a payroll application by using the corporate Intranet is 
authenticated through Kerberos authentication mechanism. However, the employee logging into the 
payroll application from outside the office must provide an x509 certificate for authentication. 


660 Configuring Authentication 


The following graphic illustrates how risk-based authentication works in this scenario: 
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Risk Assessment and Risk Mitigation after Authenticating a Login Attempt 


You can assess the potential risks associated with a particular login attempt after authenticating the 
user and then mitigate the risk, if required. In this scenario, risk-based authentication works by 
developing a risk score for each login attempt based on the following parameters: 

¢ Geographical location 

¢ Device Fingerprint 

+ IP address 

+ HTTP Header 

¢ User attributes 

+ Cookie 

¢ User last login 

+ Time of login 

+ External parameters 

+ Custom parameters 
This risk score is then evaluated against defined risk levels. The risk levels are defined based on the 
sensitivity of the information. After the risk level is identified, the user is granted or denied access. In 


cases of high risk, the user is prompted for additional authentication to confirm the user identity one 
more time and assess the validity of the request. 


For example, an employee logging into a payroll application by using the office laptop during the 
usual business hours from the same location and IP address will have a low-risk score. Whereas, an 
attempt to access the payroll application by using a personal hand-held device from non-office 
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location yields an elevated risk score. If the risk score for a user’s access attempt exceeds the 
defined risk score, the login attempt is considered as high risk, and the user might need to provide a 
higher level of authentication using a PIN or token. 


Additional authentication can be implemented by using techniques such as TOTP authentication or 
Advance Authentication Framework methods. If the risk is too high, access can be denied. For more 
information, see Section 5.3, “Advanced Authentication,” on page 645. 


The following graphic illustrates how risk-based authentication works based on specific parameters: 
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application from corporate payroll 
office in Houston application. 

using a work 

computer at 

11 a.m. PST 


Use Case 2 IP Address Time of Login Geolocation HTTP Header Device Fingerprint """ 


Entered Different Entered Different Different 
NetIQ employee Value Value Value aks 
attempts to log 
into a payroll 
application from Initial test fails. 
home using User is challenged for 
personal stronger authentication 
computer method such as OTP, 
at 6 p.m. PST biometric. 
Use Case 3 IP Address Time of Login Geolocation HTTP Header Device Fingerprint """ 


Entered Different Different Different Different 
NetIQ employee Value Value Value Value 
attempts to log into 


a payroll application 
from a different 
country that is ina 
different time zone. 


The user is denied 
access to the payroll 
application 
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Risk-based authentication helps you in achieving the following goals: 


+ Reduce fraud and the risk of improper access 


+ Enforce different levels of authentication depending on factors such as user activity and 
geolocation, and calculated risk score 
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+ Improve user experience. Users need to provide additional details for authentication only when 
the associated risk prevails 


+ Access control in federated setups 
Consider a scenario where a company named Company1 wants to protect its payroll application. 
Risk-based authentication enables Company to achieve the following actions: 

+ Restrict access to its contractual employees. 


+ Grant access to permanent employees during the company business hours between 9 a.m. to 5 
p.m. After business hours, all employees must specify a one-time password in addition to login 
credentials. 


¢ Grant special privileges to employees who work in the Finance department. For example, 
Company1 does not ask employees of the Finance department to specify a one-time password 
even if they log in after business hours. 


+ Grant access to the Self-Service tool along with the payroll application when contractual 
employees use Intranet to log in. 


+ Determine actions based on the priority of rule conditions. For example, type of employment is 
the most important criterion to grant access followed by the location of the user, and then the 
time of the login attempt. 


¢ Grant access without any additional authentication if the user has successfully logged in within 
one month. 


¢ Restrict access when an employee tries to log in from a specific geographical location. 
+ Grant or deny access based on the version of the web browser used for the login attempt. 
+ Deny access to any login attempt that originates from a handheld device. 


5.5.3 Features of Risk-based Authentication 


Risk-based authentication provides the following features: 


¢ Risk identifications by using rule definitions: Risk-based authentication helps you define 
rules that are classified as follows: 


Rule Category | Rule Description 


IP Address Use this rule to define a condition to track login attempts from an IP address, range of 
IP addresses, an IP subnet range, or a list of IP addresses from an external provider. 


For example: If you are aware that login attempts from a specific range of IP 
addresses are riskier, you can define a rule to watch for such login attempts. When a 
request originates from the specified IP address range, you can prompt for additional 
authentication. 


IMPORTANT: It is not possible to create a rule by using the IP subnet condition. 
Instead you can use the IP address range condition to select a range of IP addresses 
in the rule. 


NOTE: The IP address may not be the clients IP address, but that of an intermediate 
device. In such a case, you need to use the X-Forwarded-For to determine the IP 
address of the workstation 
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Rule Category 


Cookie 


Rule Description 


Use this rule if you want to track login attempts from a browser-based application that 
has a specific cookie value or name. 


For example: Consider a scenario where you have a financial application and a user 
accessing this application has cookies stored on the browser. If the cookie has a 
specific value or name, the user can be granted access without additional 
authentication. But, if the user accessing the application has no cookies stored, then 
you can request additional authentication to validate the user. 


HTTP Header 


Use this rule to track the HTTP header of requests based on the name or the value 
contained in the HTTP header. 


For example, if you want to track HTTP requests containing custom HTTP header 
information, you can define the action to be performed on evaluation of this rule. 


User Last Login 


This rule creates a cookie in browser after a successful step up authentication. 
Subsequent login verifies this cookie. Use this rule to define the duration for which the 
cookie is valid. On expiry of the specified duration, the user is prompted for additional 
authentication. 


For example, this rule can be used to evaluate if the user is logging in by using a 
device that was used earlier for a login attempt. You can define the risk level and also 
request additional authentication, as necessary. 


User Profile 


Use this rule to define a condition based on the LDAP attribute of the user. 


For example, you can define a rule to deny access if the employee ID of the user 
matches a specific string. 


User Time of 
Login 


Use this rule to define a condition based on the user’s attempts to login at a specific 
time. 


For example, if the usual login pattern for an employee is between 9 a.m. to 5 p.m., 
you can define a rule that takes an action if the login pattern differs from the observed 
pattern. 


Device 
Fingerprint 


Use this rule to uniquely identify and control the type of device from which a user 
could log into the applications secured by Access Manager. 


When a user log in the first time from a device and device fingerprint is not available 
for that device, a risk is added and Access Manager can be configured to prompt for 
an additional authentication. After the first successful authentication, a device 
fingerprint is calculated based on the parameters configured in the Device Fingerprint 
rule. 


In subsequent login attempts, Access Manager verifies device fingerprint parameters 
configured in the Device Fingerprint rule. 


In the current implementation, you cannot add more than one Device Fingerprint rule 
per Access Manager setup. 


For more information about device fingerprinting, see Chapter 6, “Device 
Fingerprinting,” on page 687. 


Device ID 


(Deprecated) 
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In Access Manager 4.3, this rule has been replaced with the Device Fingerprint rule. If 
you have configured any Device ID rule in Access Manager 4.1 or 4.2, this rule will be 
listed as deprecated after upgrading to Access Manager 4.3. 


Rule Category | Rule Description 


External Use this rule to consider inputs from external providers to evaluate the risk associated 
Parameters with a login attempt. 


For example, if a user is already authenticated with an external authentication 
provider, Access Manager receives authentication details from that provider such as 
the method used for the authentication. Access Manager can use this information for 
evaluating the risk. 


NOTE: To use this rule, you must create a custom authentication class to retrieve 
details from an external provider. For more information, see “User Information 
Methods” and “Creating a Custom Rule Class” in the NetIQ Access Manager 4.3 
Developer Guide. 


Geolocation Use this rule to track login attempts based on the geographical location of the user. 
You can track details ranging from a wide area such as a country or to a smaller area 
such as a region. 


For example, you can use this rule to introduce additional authentication attempts in 
the following scenarios: 


+ when a user logs in from a specific geolocation 


+ when a user accessing from a specific gelocation to be considered as a valid 
user and be granted access without further checks 


Custom Rule Lets you to define your own custom rules by using a custom Java authentication 
class. This is useful in deployments where the existing rules do not meet the 
requirements. 


For example: Consider a situation where the HTTP header contains the company 
name in an encoded format. You can create a custom rule to decode the HTTP 
header and retrieve the name of the company. This value can later be compared to an 
LDAP attribute, and based on the results, action to be taken. 


Consider a situation where a user logs in from India at a specific time each day. You 
can create a custom rule that will prevent login by the same user from USA within 24 
hours of the previous login attempt. 


For more information about creating a custom class, see VetiQ Access Manager 4.3 
Developer Guide. 


¢ Risk Engine: The risk engine evaluates and assesses rules, including risk score and risk level 
processing. It ensures that the risk associated with the login attempt is considered during 
authentication. 


¢ History: Each time a user makes a login attempt, the rules are evaluated and then based on the 
analysis, the user is either granted access or additional authentication is requested. These 
details are stored in an external database. The details recorded in history are: 


+ Risk score after evaluation of the rule 

¢ Last login time of the user 

+ Geolocation details such as city or country 

+ IP address of the client 

¢ Risk level details after evaluation of the rule 

¢ Details of additional authentication 

+ Details of error messages displayed during risk assessment 


+ Time zone details 
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It is recommended to configure Oracle, MySQL, or Microsoft SQL Server as the database to 
store the risk-based authentication data. Built-in Data Store is not recommended in a production 
environment. 


Risk Policies for risk mitigation: A risk policy is a group of risk rules. A rule must be assigned 
to a risk policy for functioning. The risk policy was called rule group in Access Manager 4.1. 


Authorization policies for protected resources: You can define a condition group as part of 
the authorization policy that uses the risk score from Identity Server to protect a resource. This 
provides an additional level of security for your environment. For more information, see 
“Configuring an Authorization Policy to Protect a Resource” on page 877. 


Risk score and risk levels validation utility: After configuring a risk policy and corresponding 
risk scores and actions, you can use the Validate utility to emulate the total risk score and the 
action in event of rule failure. The validation result indicates the total risk score and action. 
Based on these details, you can adjust the risk score and risk levels depending on your needs. 
For more information, see “Understanding How to Use the Validate Tool to Emulate Total Risk 
Score and Risk Levels” on page 680. 


Risk Rule Validation Utility: To determine the best way to implement risk levels and actions for 
your business needs, use the Risk Rule Validation Utility to test different risk rules and risk 
scores. For more information about this tool, see “Understanding How To Use the Risk Rule 
Validation Utility To Troubleshoot Rule Configuration” on page 682. 


Cumulative Scoring: You can configure to add the risk score of the current session while 
evaluating contracts. 


For example, assume that you have configured two contracts, Contract A and Contract B. 
Contract Acontains both PreAuthRiskBasedAuthenticationClass and RiskBasedAuthClass 
(post authentication). In this case, cumulative scoring is enabled in RiskBasedAuthClass. When 
Contract A is executed, RiskBasedAuthClass considers the risk score calculated by 
PreAuthRiskBasedAuthenticationClass. 


Contract Ais configured with the following two risk-based methods: 


+ A_RiskMethod1, which uses a PreAuthRiskBasedAuthenticationClass that in turn uses a 
risk policy A_SamplePolicy1. 


+ A_RiskMethod2, which uses a RiskBasedAuthClass that in turn uses a risk policy 
A_SamplePolicy2. 


For an arbitrary request, A_RiskMethod1 and A_RiskMethod2 calculate risk scores 100 and 150 
respectively. As RiskBasedAuthClass has cumulative scoring enabled, total risk score calculated 
at the end of Contract A execution is 250. 


Contract Bis configured with a method named B_RiskMethod. B_RiskMethod uses a 
RiskBasedAuthClass that in turn uses a risk policy named B_SamplePolicy. The risk score 
associated with this policy is 75. If evaluation of Contract B fails, 75 is returned as the risk 
score. If cumulative scoring is enabled, the final risk score of the session is 250 (risk score of 
Contract A) + 75 (risk score of Contract B) = 325. If cumulative scoring is not enabled, risk score 
is 75 

Risk Score Reduction after a Successful Additional Authentication: The Reduction option 
enables you to reduce the risk score by a specified value after a successful strong additional 
authentication. 


For example, Assume you want to reduce the risk score by 100 after a successful additional 
authentication. You have configured to prompt for an additional authentication when the risk 
score is more than 200. You have configured an authentication class with a risk policy that 
includes the following rules: 


+ |PAddressRule: If this rule fails, the risk score is 125 
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+ HTTPHeaderRule: If this rule fails, the risk score is 150 
+ UserProfileRule: If this rule fails, the risk score is 200 


Specify 100 in Reduction. For an arbitrary request, IPAddressRule and HTTPHeaderRule have 
failed and the effective risk score is 275. The user will be prompted for an additional 
authentication. If this authentication succeeds, the risk score becomes 175. If you have 
configured to share the risk score, the reduced risk score is shared. If you have enabled 
recording user history, the reduced value is logged. 


If the risk score value is less than one after reduction, risk score will be considered as zero. 


+ Using External Parameters in Risk Assessment: The External Parameters Rule enables you 
to consider inputs from external providers in evaluating the risk associated with a login attempt. 


For example, if a user is already authenticated with an external authentication provider, Access 
Manager can receive authentication details such as the authentication type, IP address, and 
location of the user from that provider. Access Manager can then use this information for 
evaluating the risk. 


You can configure to retrieve the input based on multiple parameters. Assume, you want to get 
the input if the user is from US and the method used to authenticate is Kerberos. Also, the user 
must not be using a device with the anti-virus software version 1.1.0.99. In this scenario, the 
configuration is as follows: 


1. Create Parameter Set 1, set logical operator as AND, and configure the following two 


parameters: 
Authentication NA Is equal to Kerberos 
Mechanism 
Location NA Is equal to US 


2. Create Parameter Set 2 and configure the following parameter: 


Anti-virus software \\d+\\.\\d+\\. \Wd+\\.\Wd+ is not equal to The version of anti- 
virus software is 
1.1.0.99. 


3. Set the logical operator between parameter sets as AND. 


NOTE: To use this rule, you must create a custom class to retrieve details from an external 
provider. For more information, see “User Information Methods” and “Creating an Authentication 
Class” in the NetlQ Access Manager 4.3 Developer Guide. 
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5.5.4 Key Terms 


Table 5-6 Risk-based Authentication Terms 


Term 


Rule 


Description 


A rule indicates a condition that you want to evaluate during a login attempt. For 
evaluation, a rule is linked to a risk policy. A rule can be assigned to multiple risk policy. 


For example, to assess the IP address of a user and the location from which the user logs 
in, you need two separate rules: One for IP address and another rule for location. 


Risk Policy 


You can combine one or more rules with a risk policy. A rule cannot be processed without 
being included in a risk policy. You can combine multiple rules in a risk policy. 


Risk Score 


The value that is returned if the rule conditions do not meet. 


For example, you have set the risk score as 50. If the risk evaluation fails, 50 is the value 
returned to the risk engine. 


Assume that the IP address rule is assigned a risk score of 50 and the geolocation rule is 
assigned a risk score of 30. If both IP address rule and geolocation rule fail, the risk score 
is 80. If only the IP address rule fails, the risk score is 50. As the geolocation rule is 
evaluated successfully, the risk score is O for this rule. 


Is/Is Not 
condition 


When you configure a rule and select a parameter for assessment, you can determine how 
the conditions must match for each of the subparameters. 


For example, if you configure a rule to assess the IP address of a user, you can configure 
whether the IP address must be specific, be in a range, or be in a particular subnet. 


For example, if you want to assess whether the IP address of a user is within a range of 
10.10.10.1 to 10.10.10.10, you can specify an Is condition in the rule configuration. This 
indicates that when the rule is evaluated, only IP addresses in the range of 10.10.10.1 to 
10.10.10.10 must be considered as a valid IP addresses and then the user must be 
granted access. 


During the rule evaluation, if you want a rule to be passed when it does not meet a specific 
criteria, select Is Not in the rule configuration screen. For example, if you want to stop all 
login attempts from a particular IP address, then configure a rule using the Is condition. 
Using the same example as above, if you want to stop any login attempts from IP 
addresses in the range of 10.10.10.1 to 10.10.10.10, configure the rule using the Is Not 
condition. 


Combination 
Rule 
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When you configure a set of rules, it is configured with the OR logical operator, by default. 


For example, if you have configured an IP address rule and a geolocation rule without any 
additional configuration, either the IP address rule is evaluated or the geolocation rule is 
evaluated. But, if you want both the IP address rule and the geolocation rule to be 
evaluated during a login attempt, configure a combination rule. A combination rule lets you 
use the AND/OR logical operators to configure a rule based on your preferences. 


For example, If you configure an IP address rule and a geolocation rule, select the AND 
operator to evaluate both rules. Whereas if you use the OR operator, either IP address rule 
or the geolocation rule is evaluated. 


on 


5.9.9 


5.5.5.1 


Term Description 


Risk Level When a rule fails to evaluate successfully, the risk score is returned to the risk engine. If 
you have multiple rules configured, for each rule that fails to evaluate successfully, the risk 
score is added up to get a cumulative score. When configuring the risk level, you can 
determine the action the risk engine has to take if the total risk score crosses a certain limit 
and the risk level for the value. 


For example, you can determine that the risk is low if the total risk score is less than or 
equal to 50. Whereas if it is greater than 50, some action is required. Here action might 
mean an additional authentication request for the user. 


Action When a risk level and the associated risk score crosses the set threshold limit, you can 
configure the action as deny access or demand additional authentication. 


For example, if you have defined a risk level of High for a cumulative risk score of greater 
than 50, then you can specify that either the user must be denied access or additional 
authentication methods must be requested. 


Understanding Risk-based Authentication through 
Scenarios 


The following are few example configuration to describe how you can use risk-based authentication: 


¢ Scenario 1 
¢ Scenario 2 
¢ Scenario 3 
¢ Scenario 4 
¢ Scenario 5 
¢ Scenario 6 


Scenario 1 


You want to enable two-factor authentication for a user outside the corporate network, and single 
factor authentication when the user is in the corporate network. 


You can configure risk-based authentication in this scenario by using Risk-based Pre-Auth Class. 
You can determine the authentication method required for an access based on the context before the 
user's identity is validated through authentication. You can choose from many authentication methods 
and apply them as per your security policy requirements. 


For example, you can enable a simple username/password prompt when the user is in the internal 
network. If the user is trying to login from outside the corporate network using a known device, prompt 
for Advanced Authentication Framework (username/password and smartphone) authentication. 


Configuration Steps: 


1 Go to Policies > Risk-based Policies > Risk Policy. 
2 Click the Create Risk Policy icon. 
3 Under Add Risk Policy, specify the following details: 
Risk Policy Name: Specify a name. 
Policy Description: Specify the purpose of this policy. 


Configuring Authentication 669 


Assign Policy To: Select Identity Server cluster and then configure an authentication class. 
+ Select Risk-based Pre-Authentication Class. 
+ Specify Display Name. 
+ Click Save. 
4 Create an IP Address rule. 
4a Under Policy Rules, click Create Rule and specify the following values: 
+ Rule Name: Specify a name. 
¢ Rule Definitions: Select IP Address Rule. 
¢ Select Allow if IP Address Is in the list. 


¢ Specify the corporate IP Address details. For more information, see “IP Address” in 
Step 3 on page 829. 


4b Click OK. 
4c If rule condition is met, then: Exit with Risk level as. 
4d Select Risk Level: Low 
4e Click OK. 
5 Create a Device ID rule. 
5a Under Policy Rules, click Create Rule and specify the following values: 
+è Rule Name: Specify a name. 
¢ Rule Definitions: Select Device ID Rule. 
+ Specify the details. For more information, see “Device ID” in Step 3 on page 829. 
5b Click OK. 
5c If rule condition is met, then: Exit with Risk level as. 
5d Select Risk Level: Medium 
5e If rule condition is not met, add risk score: 50 
5f Click OK. 
6 Under Risk Levels, click Actions > Add Risk Level and create the following risk levels: 


+*+ Low 
Field Value 
Risk Score Less than 50 
Risk Level Low 
Action Authenticate by using Name/Password - Basic 
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+ Medium 


Field Value 

Risk Score Equals to or greater than 50 

Risk Level Medium 

Action Authenticate by Advanced Authentication Framework 


(username/password and smartphone) 


NOTE: To enable this configuration, you must configure 
Advance Authentication Framework with Access Manager. For 
more information, see Access Manager - Advanced 
Authentication Plugin User Guide. 


7 Click OK. 


8 Create an authentication method. For more information, see “Configuring a Method for an 
Authentication Class” on page 828. 


9 Create a contract. For more information, see “Configuring a Contract for an Authentication 
Class” on page 828. 


10 Assign the contract to the protected resource. 


5.5.5.2 Scenario 2 


You want to configure an authentication mechanism or an additional authentication mechanism 
based on the type of the device. 


You can configure risk-based authentication in this scenario by using Risk-based Pre-Auth Class. 
You can create a risk rule to choose an authentication mechanism or an additional authentication 
mechanism based on the type of device used by a user. 


For example, if a user is logging in from a mobile device, you can prompt the user to provide an 
additional authentication such as SMS or One-Time Password based authentication after the user is 
authenticated. You can define an HTTP Header rule by using a user-agent property such as Mozilla/ 
5.0 (iPhone; U; CPU iPhone OS 3_0) to verify whether the request is from a mobile. 


Configuration Steps: 


Click Risk-based Policies > Rules. 

Specify a name for the rule. 

Select HTTP Header Rule. 

Specify HTTP Header Name as X-Forwarded-For. 


Select Contains in HTTP Header Value and specify Mozilla/5.0 (iPhone; U; CPU iPhone OS 
3_0). 


ao fF OO N FP 


NOTE: You must configure NAT settings for this rule to work. See “Configuring NAT Settings” on 
page 834. 


6 Click OK. 
7 Assign the rule to a risk-policy and follow steps Step 7 to Step 9. 
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Scenario 3 


You want to grant access only to employees. You want to deny access for any request from a specific 
region even if the user is an employee of your organization. 


This scenario requires to create two separate rules: one for geolocation named 
example_geolocation and another for user profile named example_user_profile. 


You can configure risk-based authentication for this scenario by using Risk-based Auth Class. 


Configuration Steps: 


1 


Go to Policies > Risk-based Policies > Risk Policy. 


2 Click the Create Risk Policy icon. 


3 Under Add Risk Policy, specify the following details: 


Risk Policy Name: Specify a name. 
Policy Description: Specify the purpose of this policy. 
Assign Policy To: Select Identity Server cluster and then configure an authentication class. 
+ Select Create Risk-based Auth Class. 
+ Specify Class Name. 
+ Click Save. 
Create a Geolocation rule and a User Profile rule. 
+ Geolocation Rule 


Under Policy Rules, click Create Rule and specify the following values: 


NOTE: You must configure a provider in the Geolocation user interface for a geolocation 
rule to work. 


è Rule Name: Specify example_geolocation. 
+ Rule Definitions: Select Geolocation Rule. 


+ User Location: Select Is not. 


Specify the following geolocation details of the region which you want to deny all login 
requests from: 


Country Code 
State Name 
State Code 
City Name 
Zip Code 
Metro Code 
Area Code 
Region Code 
Region Name 


¢ If rule condition is met, then: Allow Access and Exit Policy 
+ If rule condition is not met, add risk score: 60 
+ Click OK. 

+ User Profile Rule 
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Under Policy Rules, click Create Rule and specify the following values: 


+ 


+ 


+ 


Rule Name: Specify example_user_profile. 

Rule Definitions: Select User Profile. 

Select employeeType. 

Select Equals. 

Specify Employee. 

If rule condition is met, then: Proceed to Next Rule 
If rule condition is not met, add risk score: 60 

Click OK. 


To evaluate example_user_profile first, drag it up before example_geolocation in the 
rules list in Administration Console. 


5 Under Risk Levels, click Actions > Add Risk Level and create the following risk level: 


For more information about risk scores, see “Risk Score” in Table 5-6, “Risk-based 
Authentication Terms,” on page 668. 


Field Value 
Risk Score Equals to or greater than 50 
Risk Level High 
Action Deny Access 
6 Click OK. 


7 Create an authentication method. For more information, see “Configuring a Method for an 
Authentication Class” on page 828. 


8 Create a contract. For more information, see “Configuring a Contract for an Authentication 
Class” on page 828. 


9 Assign the contract to the protected resource. 


Scenario 4 


If the user is an employee and is not located in a specific region, grant the access. If the user is an 
employee, but accessing from a specific region, deny the access. If the user is an employee and 
accessing from the specified location, but the HTTP header contains a specified email ID, grant the 


access. 


You can configure a risk policy for this scenario by using the combination rule. A combination rule 
assesses more than one parameter to validate an authentication request from a user. 


The rule must assess the user profile and geolocation first and consider the HTTP header condition 
only when the first condition evaluation fails. 


You can configure risk-based authentication in this scenario by using Risk-based Auth Class. 


Configuration Steps: 


1 Go to Policies > Risk-based Policies > Risk Policy. 


2 Click the Create Risk Policy icon. 
3 Under Add Risk Policy, specify the following details: 
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Risk Policy Name: Specify a name. 
Policy Description: Specify the purpose of this policy. 
Assign Policy To: Select Identity Server cluster and then configure an authentication class. 
+ Select Create Risk-based Auth Class. 
+ Specify Class Name. 
+ Click Save. 
4 Create a Geolocation rule and a User Profile rule as a single rule. 
4a Under Policy Rules, click Create Rule and specify the following values: 
4b Rule Name: Specify example_combination_rule. 
4c Configure the geolocation rule. 


NOTE: You must configure a geolocation provider in the Geolocation user interface for this 
rule to work. 


4c1 Rule Definitions: Select Geolocation Rule. 

4c2 User Location: Select Is not. 

4c3 Specify the following geolocation details of the region which you want to deny all login 
requests from: 


Country Code 
State Name 
State Code 
City Name 
Zip Code 
Metro Code 
Area Code 
Region Code 
Region Name 
4d Click Combine with to add the user profile rule. 
4d1 Select User Profile Rule. 
4d2 Under User Attributes, Select enployeeType and Equals, and specify Employee. 
4e Click Combine with to add the HTTP Header rule. 
4e1 Select HTTP Header Rule. 


4e2 Specify the HTTP header Name and the specific HTTP header value that you want to 
search for an HTTP header. 


4 


= 


In Combination Rule Definition > Condition Group, click Assign Rules and then select user 
profile and geolocation rules. Select AND in Group Operator. For information about how 
these operators work, see “Combination Rule” in Table 5-6, “Risk-based Authentication 
Terms,” on page 668. 


4g Click Add Condition Group and select HTTP Header Rule. 
4h Select the OR operator for Condition Group 1 and Condition Group 2. 
4i 
4j If rule condition is not met, add risk score: 50 
4k Click OK. 
5 Under Risk Levels, click Actions > Add Risk Level and create the following risk levels: 


If rule condition is met, then: Allow Access and Exit Policy. 
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You can define actions for a risk score or for a range of risk score. When evaluation of all 
conditions in a risk policy fail, the action is taken based on the accumulated risk score. 


For more information, see “Risk Score” in Table 5-6, “Risk-based Authentication Terms,” on 


page 668. 

* Low 
Field Value 
Risk Score Less than 30 
Risk Level Low 
Action Allow Access 

+ Medium 
Field Value 
Risk Score Between 30 and 50 
Risk Level Medium 
Action Authenticate using Trust levels 

+ High 
Field Value 
Risk Score Equals to or greater than 50 
Risk Level High 
Action Deny Access 

6 Click OK. 


7 Create an authentication method. For more information, see “Configuring a Method for an 


Authentication Class” on page 828. 


8 Create a contract. For more information, see “Configuring a Contract for an Authentication 


Class” on page 828. 
9 Assign the contract to the protected resource. 


Scenario 5 


You want to store the details of login attempts in the configured history databases and take actions 


based on these details in subsequent login attempts. 


While configuring risk-based authentication, you can determine if you want to save the history details 
and the number of days for which history to consider for evaluation of the authentication attempt. 


For example: Let us assume that you have enabled recording of history details and have specified 
that the history of last 10 days are used for evaluation before granting or denying access. If the user 
logs in from a different geolocation, additional authentication is requested as the risk is high. The risk 
evaluation details are stored in the database. Next time the user logs in from the same geolocation, 
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5.5.5.6 


5.9.6 


the historical details for the last ten days are checked to see if there are details about a login attempt 
from the same geolocation. As the geolocation details exist in the database, the user is granted 
access without being prompted for additional authentication. 


You can enable recording of user history only for a risk policy that uses Risk-based Auth Class. 


For more information about how to enable recording of user history, see “Configuring User History” on 
page 833. 


Scenario 6 


You want to identify the characteristics or fingerprints of devices users use for login. The device can 
be a desktop, a laptop, or a mobile device. You want this information to achieve the following 
activities: 


+ Uniquely identify users’ devices used in login attempts 


+ Use the device identification details in evaluating risks associated with a login attempt and 
decide the action based on the risk. 


You can configure a risk policy for this scenario by using the Device Fingerprint rule. The Device 
Fingerprint rule enables you to identify user devices previously used for access. A fingerprint can be 
imprinted on the device itself or stored to the risk database. In pre-authentication scenarios, the 
device fingerprints consist of the device characteristics. In post-authentication scenarios, the device 
fingerprints consist of the device characteristics and user identifier. 


For example, when a user logs in the first time through a laptop, the user needs to provide an 
additional authentication. After the successful additional authentication, a device fingerprint is 
computed and stored either in the device (without any user information) or in the database (tied to the 
user). If the rule is configured for a pre-authentication scenario, the details are stored in the browser 
cache on the device. For a post-authentication scenario, you can configure to save these details in 
the browser cache or a risk database.When the user logs in next time, the device fingerprint of this 
device is computed and matched with the stored values. If the value does not match, the user is 
asked for additional authentication or a risk is added to the session. 


For an example configuration, see Section 6.4, “Configuring an Example Device Fingerprint Policy,” 
on page 693. 


Understanding Risk Score Calculation 


A risk score is assigned when a rule is added to a risk policy. This risk score indicates the priority and 
criticality of the rule. 


For example, if you have configured a set of rules, but you want one rule to be the most important 
rule, assign it a higher risk score compared to the other rules. If the rule evaluation is successful, the 
risk score is set as zero. 


If a rule evaluation is not successful, the risk score is set as the value of the rule. If you have 
configured multiple rules, the total risk score is the sum of risk scores of all the failed rules. 


¢ Section 5.5.6.1, “Scenario 1,” on page 677 
¢ Section 5.5.6.2, “Scenario 2,” on page 677 
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5.5.6.1 


5.5.6.2 


Scenario 1 
Let us assume that you have created two rules to validate login requests to a financial application. 


You have determined that Rule 1 is the most critical rule and want users to gain access when this rule 
is evaluated. 


Table 5-7 Risk Rules 


Rules If rule condition is met, then 
Rule 1 50 Allow access and exit policy 
Rule 2 30 Return risk level low 


Depending on the risk score returned after evaluation of rule, risk level is assigned and action is 
taken. 


Table 5-8 Risk Scores and Risk Levels 


Total Risk Score Risk Level Action 


31-80 Medium Additional authentication must be requested. 


0-30 Low Allow access. 
The following table describes how the rules are evaluated: 


Table 5-9 Risk Score Calculation for the Rules 


Scenario Details Total Risk Score | Action 
Rule 1 is successfully | Rule 2 is not considered for rule 0 Access is allowed. 
evaluated. processing as Rule 1 is configured to 


exit the policy when condition is met. 


Rule 1 and Rule 2 In this case, the total risk score is 80 80 Additional 
fail. as both the rules have failed. authentication is 
requested. 
Scenario 2 


You have created three rules to access login requests to a financial application. All the rules must 
evaluate successfully to grant access to the user. 


Table 5-10 Risk Rules 


Rules Risk Score If rule condition is met, then 
Rule 1 50 Proceed to Next Rule 

Rule 2 30 Proceed to Next Rule 

Rule 3 10 Exit with Risk Level as...Low 
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Depending on the risk score returned after evaluation of rule, risk level is assigned and action is 
taken. 


Table 5-11 Risk Scores and Risk Levels 


Total Risk Score Risk Level Action 

0-30 Low Allow access 

31-50 Medium Additional authentication 
51-100 High Deny access 


5.5.7 


5.5.8 
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The following table describes how the rules are evaluated: 


Table 5-12 Risk Score Calculation for the Rules 


Scenario Details Total Risk Score Action 

Rule 1, Rule 2, and Rule 3 | As all the rules are evaluated 0 Access is allowed. 
are successfully evaluated. | without errors, the risk score is 0. 

Rule 1 evaluates The risk score is the value 40 Additional 
successfully, but Rule 2 assigned to the rule that failed. In authentication is 
and Rule 3 fail. this case, the risk score is 40. requested. 

Rule 1 fails, but Rule 2 and | The risk score is the value 50 Additional 

Rule 3 evaluate assigned to the rule that failed. In authentication is 
successfully. this case, the risk score is 50. requested. 

Rule 2 evaluates The risk score is the sum of risk 60 Access is denied. 
successfully, but rule 1 and_ | scores of all failed rules. In this 

rule 3 fail. case, the risk score is 60. 

Rule 2 fails, but rule 1 and The risk score is the sum of risk 30 Access is allowed. 
rule 3 evaluate scores of all failed rules. In this 

successfully. case, the risk score is 30. 

All the rules fail. The risk score is the sum of risk 90 Access is denied. 


scores of all failed rules. In this 
case, the risk score is 90. 


Configuring Risk-based Authentication 


For information about configuring risk-based authentication, see Section 8.7, “Risk-based Policies,” 


on page 865. 


Enabling Auditing for Risk-Based Authentication Events 


For information about risk-based authentication events and how to enable these, see Section 19.2, 
“Enabling Identity Server Audit Events,” on page 1021. 
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5.5.9 Configuring an External Database to Store User History 


Access Manager supports MySQL, Oracle, and Microsoft SQL Server databases for storing risk 
history. This section provides details about how to configure these databases. 

¢ Section 5.5.9.1, “Configuring MySQL Database,” on page 679 

¢ Section 5.5.9.2, “Configuring Oracle Database,” on page 679 

¢ Section 5.5.9.3, “Configuring Microsoft SQL Server,” on page 679 


5.5.9.1 Configuring MySQL Database 


1 Unzip the RiskDBScripts. zip file containing script to extend the database and sample 
configuration files. The file is located at the following location: 


On Linux: /opt /novell/nids/1ib/webapp/WEB- INF/RiskDBScripts. zip 


On Windows: C:\Program Files\(x86)\Novell\Tomcat \webapps\nidp\WEB- 
INF\RiskDBScripts. zip. 


2 On the MySQL server, execute the following command to create database objects for risk-based 
authentication: 


mysql -h host -u username -p password netiq_risk_mssql_install.sql 
3 Download the JDBC connector for the MySQL database from MySQL.com. 
4 Copy the JDBC connector to the /opt/novell/nids/1ib/webapp/WEB- INF/1ib/ folder. 
5 Restart Identity Server. 


5.5.9.2 Configuring Oracle Database 
1 Unzip the RiskDBScripts.zip file containing script to extend the database and sample 
configuration files. The file is located at the following location: 
On Linux: /opt/novell/nids/1lib/webapp/WEB- INF/RiskDBScripts. zip 


On Windows: C:\Program Files\(x86)\Novell\Tomcat \webapps\nidp\WEB- 
INF\RiskDBScripts. zip. 


2 On the Oracle server, execute the following script to create database objects for risk-based 
authentication: 


netiq_risk_oracle_install.sql 
3 Download the JDBC connector for the Oracle database from Oracle.com. 
4 Copy the JDBC connector jar to the /opt /novell/nids/1ib/webapp/WEB-INF/1ib/ folder. 
5 Restart Identity Server. 


5.5.9.3 Configuring Microsoft SQL Server 


1 Unzip the RiskDBScripts. zip file containing script to extend the database and sample 
configuration files. The file is located at the following location: 


On Linux: /opt/novell/nids/lib/webapp/WEB-INF/RiskDBScripts. zip 


On Windows: C:\Program Files\(x86)\Novell\Tomcat \webapps\nidp\WEB- 
INF\RiskDBScripts. zip. 


2 On the SQL Server, execute the following script to create database objects for risk-based 
authentication: 
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5.9.10 


5.5.11 


5.5.11.1 


netiq_risk_sql_server_install.sql 


3 Download the JDBC connector for the SQL Server database from Microsoft.com (https:// 
www.microsoft.com/en-in/download/details.aspx?id=11774). 


4 Copy the JDBC connector file sqljdbc42.jar to the /opt/novell/nids/1lib/webapp/WEB- 
INF/1ib/ folder. 


5 Restart Identity Server. 


Enabling Logging for Risk-Based Authentication 


1 Click Devices > Identity Servers > Edit > Auditing and Logging. 
2 Select Enabled under File Logging. 


3 In the Component File Logger Levels section, specify any one of the following options for 
application logs: 


+ Severe: Logs serious failures that can stop system processing. 

+ Warning: Logs potential failures that have minimal impact on execution. 
¢ Info: Logs informational events. 

+ Verbose: Logs static configuration information. 


The system logs any configuration errors under one of the three primary levels: Severe, 
Warning, and Info. 


+ Debug: Logs events for all other log levels: Severe, Warning, Info, and Verbose. 


For more information, see Section 21.3, “Identity Server Logging,” on page 1038. 


Troubleshooting Risk Rule Configuration 


The following sections describe how to troubleshoot rule configuration: 
¢ Section 5.5.11.1, “Understanding How to Use the Validate Tool to Emulate Total Risk Score and 
Risk Levels,” on page 680 


¢ Section 5.5.11.2, “Understanding How To Use the Risk Rule Validation Utility To Troubleshoot 
Rule Configuration,” on page 682 


¢ Section 5.5.11.3, “Troubleshooting Rule Evaluation Details By Using the Log File,” on page 682 


Understanding How to Use the Validate Tool to Emulate Total Risk 
Score and Risk Levels 
After configuring a risk policy and the corresponding risk scores and actions, use Validate to emulate 


total risk score, risk level, and action in event of rule failure. Based on the results, you can modify the 
configuration, if required. 


Let us consider a case where you have configured a risk policy that includes five rules. The rules and 
the corresponding risk scores are as follows: 
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Table 5-13 Sample Risk Policy Configuration: Rules 


Risk Policy Name | Rule Risk Score 


Demo_RiskPolicy | Demo_InNetworkAtOfficeHours 20 


Demo_InternalUser 20 
Demo_KnownDevice 20 
Demo_PayrollSiteCookie 20 
Demo_UserProfile 20 


Table 5-14 Sample Risk Policy Configuration: Risk Scores and Risk Levels 


Risk Score Risk Level Action 

Less than 30 Low Allow access 

Between 30 to 60 Medium Authenticate with class Trust Levels 
Greater than 60 High Deny access 


Now, open the risk policy for which you want to emulate total risk score, risk level, and action in event 
of rule failure. In the risk policy page, click Actions > Toggle Validate. Specify the rules as pass or fail 
to see the result along with a graphical reperesentation. 


For example, specify pass and fail for rules as follows: 


Rule Condition 
Demo_InNetworkAtOfficeHours Failed 
Demo_InternalUser Failed 
Demo_KnownDevice Failed 
Demo_PayrollSiteCookie Passed 
Demo_UserProfile Passed 


In this case, the validation result is as follows: 


#8 Policy Rules Actions s Validation Result 
Action Risk Score Validate E 
REK Rii (when rule condition is met) (when rule condition is not met) (when met) - Madama 
High 
DemoRule_InternalNetwork «7 Allow Access 20 4 +2 m Fails 
DemoRule_TraineeUser [S] Deny Access 20 y + [2 m (] Fails 
Medium 190 ~ 
DemoRule_KnownDevice € Return risk level 'Medium 20 Vv + 2 w 
Risk Score 60 
DemoRule_Combo vV Proceed to next rule 20 Vv + 7 WW | Pass f Risk Level Medium 
DemoRule_TimeOfLogin } Proceed T eaxt male 20 4 +a | Pass ff Risk Action Authenticate with dass Trust Levels 


You can similarly specify any other rule as failed or passed to emulate the risk score and risk levels. 
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5.5.11.2 


5.5.11.3 


Understanding How To Use the Risk Rule Validation Utility To 
Troubleshoot Rule Configuration 


After configuring a risk policy, you can use the Risk Rule Validation utility to evaluate the configuration 
of rules. This helps you understand how rules are evaluated in a risk policy. 


During rule evaluation if there is a match with the values configured for the rules, the rule evaluation is 
successful. If no match is found, the rule evaluation fails. 


Using the Risk Rule Validation Utility to Test Risk Configuration 
To use the risk rule validation utility for testing risk configuration, perform the following steps: 


1 In the browser address bar, type the following URL: 
https://<identity-server -base-url>:port/nidp/test/risk 
For example: https://10.1.1.1:8443/nidp/test/risk 

2 Specify the credentials to log in. 


3 Select a risk policy for evaluation. Click Submit. The risk score, risk category evaluation results 
and HTTP request header and related information are displayed. 


4 [Optional] If you have logged in with administrator privileges, click Details to view details about 
risk configuration. 


NOTE: The Risk Rule Validation utility does not display details if Record User History is enabled 
and a user profile rule is configured. 


Troubleshooting Rule Evaluation Details By Using the Log File 
You can troubleshoot rule evaluation details by performing the following details: 

¢ “Prerequisite” on page 682 

e “Using Logs to Understand How Rules are Evaluated” on page 682 
Prerequisite 


Ensure that you have enabled logging at the application level. For more information see, “Enabling 
Logging for Risk-Based Authentication” on page 680. 


Using Logs to Understand How Rules are Evaluated 


If you encounter any error during risk-based authentication, check the log files to review the error 
code. The log file location is: 


Linux: /opt/novell/nam/idp/logs/catalina. out 
Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.1log 


Consider a scenario where you have three rules configured as described in Table 5-13. Using this 
scenario as an example let us see how we can use the details in catalina. out file to understand 
how rules are evaluated. 

¢ “Scenario 1: User Profile Rule Fails” on page 683 


¢ “Scenario 2: User Profile Rule Evaluates Successfully” on page 683 
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¢ “Scenario 3: Two rules fail and the user is asked to authenticate using additional authentication” 
on page 684 


¢ “Scenario 4: All Rules Fail” on page 685 
Scenario 1: User Profile Rule Fails 


In this scenario the User Profile rule fails to evaluate successfully. All other rules in the risk policy 
evaluate successfully. 


The following tracelist detail from catalina. out file provides more information about rule evaluation, 
risk score, and action: 


Figure 5-20 Tracelist providing information about rule evaluation 
traceList RL~groupN ame~MultiGP~ruleCount~3~Success~riskScore~30 
RU ~~user-profile~~neg ateResult~fals e~ex ceptionRule~false~result~false~ 
RU ~~http-header~~negateR esult~false~exce ptionRule~false~res ult~true~ 
CO~~ actualValue~hrba-value~string-compare~ex pectedValue~hidden-v alue~result~true~ 
RU ~~ip-rule~~negateR esult~false~exce ptionRule~false~res ult~true~ 


CO~~ clientIP~10.30.30.50~in-range~hidden~param eters~res ult~true~ 
</amLogEntry> 


Table 5-15 Description of details recorded in the catalina. out file. 


Entry Description 


user-profile~result~false Indicates that user profile rule failed and the risk score 
of 30 is added to the total risk score. 


http-header~result~true Indicates that the HTTP header rule evaluated 
successfully. 


ip-rule~result~true Indicates that the IP address rule evaluated 
successfully. 


Figure 5-21 Tracelist providing information about risk level and action 


<amLogEntry> 2015-03-16T05:29:18Z INFO NIDS Application: User. admin risk action: ALLOW risk score: 30 
</amLogEntry> 


This log entry indicates that the as per the risk level/action configuration, the action taken is to allow 
authentication to the user and the risk score is 30. 


Scenario 2: User Profile Rule Evaluates Successfully 


In this scenario the User Profile rule evaluates successfully. As this rule is a configured to exit when 
conditions is met, all other rules in the risk policy are not considered for evaluation. 


The following tracelist detail from catalina. out file provides more information on the rule evaluation, 
risk score and action. 
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Figure 5-22 Tracelist providing information about rule evaluation 


taceLlist: RL~groupName~MultGP~ruleCount-3~ Success~riskScore~0 
RU~~user-profile ~~ ne ga teResult~false~ exce pt ionRule~ true ~result~true~ 
CO~~ actualVabe~usert~string-2q uals~expe cted Value ~hidden-value~result~true~ 
</amLogE ntre 


Table 5-16 Description of details recorded in catalina. out file 


Entry Description 


user -profile~result~true Indicates that user profile rule evaluated successfully. 


Figure 5-23 Tracelist providing information about risk level and action 


<amLogEnty> 2015-02-16T05:28:07Z INFO NIDS Application: User: user? risk action: ALLOW risk score: 0 </4amLogEntry 


This log entry indicates that the as per the risk level/action configuration, the action taken is to allow 
authentication to the user and the risk score is 0. 


Scenario 3: Two rules fail and the user is asked to authenticate using additional 
authentication 


In this scenario User Profile rule and the IP address rule fail to evaluate successfully. The HTTP 
header rule evaluates successfully. 


The following tracelist detail from catalina. out file provides more information on the rule evaluation, 
risk score and action. 


Figure 5-24 Tracelist providing information about rule evaluation 


traceList RL~groupName~MultiGP~ruleCount~3~Success~nskScore~55 
RU~~user-profile~~negat eResult~-false~exceptionRule~false~result~false~ 
RU~~http-header~~negat eResult~false~exceptionRule~false~result~true~ 
CO~~ actualValue~hrba-v alue~string-compare~ex pecte dV alue~hidden-value~result~true~ 
RU~~ip-rule~~negateResultt~false~ex ceptionRule~false~result~false~ 
CO~~ dienti P- ~in-range~hidden~parameters~result~false~ 
</amLogEntry> 
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Table 5-17 Description of details recorded in the catalina.out file 


Entry Description 
user-profile~result~false Indicates that user profile rule failed and the risk score 


of 30 is added to the total risk score. 


http-header~result~true Indicates that the HTTP header rule evaluated 
successfully. 


ip-rule~result~false Indicates that the IP address rule failed and the risk 
score of 25 is added to the total risk score. 


Figure 5-25 Tracelist providing information about risk level and action 


<amLogEntry> 2015-03-16T05:28:56Z INFO NIDS Application: User: admin risk action: STEP_UP/Additional authentication risk score: 55 
</amLogEntry> 


This log entry indicates that the as per the risk level/action configuration, the action taken is additional 
authentication and the risk score is 55. 


Scenario 4: All Rules Fail 
In this scenario, all rules fail to evaluate successfully. 


The following tracelist detail from catalina. out file provides more information on the rule evaluation, 
risk score and action. 


Figure 5-26 Tracelist providing information about rule evaluation 


taceList!) RL~groupNsme~MultiGP~uleC ount-3~Success ~risk Score~75 
RU ~-user-profile~~negateRss ult~fal e~exceptionRule~-fabe~esult~false~ 
RU ~http-hesder~~negsteRes ult~fab e~exceptionRule~fabe~result~fabe~ 
CO~~ sctus!Vslue~null~string-compare~expectedValue~hidden-value~res ult~fabe~ 
RU ~ip+ule~~negsteRes ult~fab e~exceptionRule~fab e~res ult-fabe~ 
CO~~ clientIP~ ~in-range~hidden~parameters ~res ult~fabe~ 
“amLogEntry> 


Table 5-18 Description of details recorded in the catalina.out file 


Entry Description 
user-profile~result~false Indicates that user profile rule failed and the risk score 


of 30 is added to the total risk score. 


http-header~result~false Indicates that the HTTP header rule failed and the risk 
score of 20 is added to the total risk score. 


ip-rule~result~false Indicates that the IP address rule failed and the risk 
score of 25 is added to the total risk score. 


Figure 5-27 Tracelist providing information about risk level and action 


<amLogEntry> 2015-03-16T05:27:52Z INFO NID S Application: User. admin risk action: DENY risk score: 75 <famLogEntry> 
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This log entry indicates that as per the risk level/action configuration, the action is to deny access to 
the user and the risk score is 75. 
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6 Device Fingerprinting 


6.1 


The device fingerprinting feature enables you to identify the type of device from which a user can log 
in to the applications secured by Access Manager. The device can be a desktop, a laptop, or a mobile 
device. Each device has many characteristics such as operating system, hardware, browser 
characteristics. Access Manager uses device characteristics and user identity to create a unique 
fingerprint of the device. You can use the fingerprint to uniquely identify and associate a risk profile for 
the device. You can further configure what kind of applications can be accessed through this device. 


You can use the device fingerprint information to achieve the following activities as part of risk-based 
authentication: 
+ Uniquely identify users’ devices used in login attempts 
¢ Evaluate risks associated with a login attempt by using device identification details and decide 
the action based on the risk 


This section provides details about how device fingerprint works in risk-based authentication and how 
to configure a risk-based authentication policy to utilize device fingerprinting capabilities. For more 
information about risk-based authentication, see Section 5.5, “Risk-based Authentication,” on 

page 658. 


This section includes the following topics: 


¢ Section 6.1, “How It Works,” on page 687 

¢ Section 6.2, “Understanding Device Fingerprint Parameters,” on page 691 

¢ Section 6.3, “Configuring a Device Fingerprint Rule,” on page 693 

¢ Section 6.4, “Configuring an Example Device Fingerprint Policy,” on page 693 
¢ Section 30.9, “Troubleshooting the Device Fingerprint Rule,” on page 1244 


How It Works 


When a user logs in the first time, the user needs to provide an additional authentication. After the 
first successful authentication, Identity Server calculates the fingerprint for a device by using various 
user and device attributes and registers the device. In subsequent login attempts by the same user, 
Identity Server validates the device by using the stored fingerprint. 


You can configure to store the fingerprint in any of the following locations: 


¢ Browser: You can use this option in both risk-based pre-authentication scenarios and risk- 
based post-authentication scenarios. The fingerprint is valid for the duration specified in the rule. 
Each device has a single and unique fingerprint. So, this option will not work if the device is 
shared among more than one user and the fingerprint is configured to use the user DN 
parameter. 


¢ Server: You can use this option only in risk-based post-authentication scenarios. The user can 
use many devices to log in, such as desktop, laptop, and various hand-held devices. You can 
save up to 20 device fingerprints for a user. 
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Device Fingerprinting in Pre-authentication Scenario 


The following diagram illustrates how Access Manager device fingerprinting works in pre- 
authentication scenarios: 


Identity Server 


Login Request 
Evaluate Risk 
(Fingerprinting 
Rule Enabled) 
Match Fingerprint 


Authentication 
Mechanism 1(Low Risk) 
Authentication 
Mechanism 2(High Risk) 
Authenticate User 
User Store 
Store fingerprint in 
device and allow access 


1. Auser tries to log in. 
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2. Identity Server calculates the fingerprint of the device being used in the login attempt. 


. Identity Server matches this device fingerprint with the existing device fingerprint if any exists. 


4. lf the device fingerprint matches, the user is prompted to authenticate with an authentication 


mechanism configured for a low-risk login attempt. If the device fingerprint does not match, the 
user is prompted to authenticate with an authentication mechanism configured for a high-risk 
login attempt. 


5. Identity Server authenticates the user. 


6. If the authentication is successful, Identity Server saves the fingerprint in the device and 


redirects the user to the service provider. If the authentication fails, Identity Server denies the 
user request. 
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Device Fingerprinting in Post-authentication Scenario 


The following diagram illustrates how Access Manager device fingerprinting works in post- 


authentication scenarios: 


Login Request 


Device Fingerprinting 


Identity Server 


Authenticate User 


User Store 


Authenticated? 4 


Evaluate Risk (Fingerprinting 
Rule Enabled) 


Match Fingerprint 


Match? b 


Update Fingerprint with 
new expiry time 


Do Risk Action(Stepup 
authentication) 


Stepup 
Success? 


Store fingerprint in 
device and allow access 


Deny 
Access 


A user tries to log in. 
The user specifies login credentials. 


Identity Server authenticates the user. 


Bie I= 


After a successful authentication, Identity Server calculates the fingerprint of the device that the 
user has used for logging in. 


5. Identity Server matches this device fingerprint with the existing device fingerprint if any exists. 


6. If the device fingerprint matches, Identity server updates the expiry time of the existing device 
fingerprint and redirects the user to the service provider. 


7. If the device fingerprint does not match, a risk is added to the session. The user is prompted for 
an additional authentication. 


8. If the additional authentication is successful, Identity Server saves this device fingerprint and 
allows access to the resource. 


9. If the additional authentication fails, Identity Server denies the user’s request. 


6.2 Understanding Device Fingerprint Parameters 


A device fingerprint consists of a number of parameters. The following table lists supported 


parameters: 
Parameter Description 
Request Header Set Fetches Accept, Accept-Charset, Accept-Encoding, and Accept- 
Language from the request headers of the incoming request. 
User DN Fetches the distinguished name of a user in the user store. 
This parameter is not applicable for pre-authentication risk 
analysis. 
Hardware Parameters Fetches the following details about the user’s device: 
+ Touch support 
+ Maximum number of supported touch points 
+ CPU architecture (32- or 64-bit processor) 
+ Color depth 
+ type (mobile, desktop, or iPad) 
Language Set Fetches language preferences of the user's device. 
Operating System Fetches name and version of the operating system on the user’s 
device. 
Screen Resolution Fetches width and height of the user's browser and screen. 
Time Zone Offset Fetches time zone of the user's device. 
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Parameter Description 


User Agent Fetches the following details about the browser on the user’s 
device: 


+ Version 
+ Name 
+ Platform of the browser 


+ Number of logical processor cores available to the browser 


Selecting the following parameters might impact performance: 


HTML5 Capabilities Fetches the information about HTML 5 capabilities that are 
supported by the browser. 


System Fonts Fetches the information about fonts supported and unsupported 
by the user's browser. 


WebGL Metadata Fetches information about the Graphics Processing Unit (GPU), 
the identity of the browser, Web Graphics Library (WebGL) 
properties, and characteristics supported by the browser. 


WebGL is a JavaScript API for rendering interactive 3D computer 
graphics and 2D graphics within any compatible web browser 
without using plug-ins. 


You can configure the match criteria either for an individual parameter or for a group of parameters. 
An individual parameter must match exactly with the stored value. You should configure a parameter 
for individual validation if it must be part of the login request and its value does not change frequently. 


Consider configuring a parameter to be evaluated as a group if it is less important and the parameter 
value may change frequently. For example, version of a browser. For a group of parameters, you can 
specify a value in percentage. To meet the rule condition, the specified percentage of the parameters 
in the group must match with the stored value. 


Selecting parameters for a group evaluation and specifying the match criteria to 100% gives similar 

result as the individual parameters evaluation. However, this configuration is not recommended, as it 
results in additional back-end percentage calculations. Instead, add the parameters in the individual 

list based on requirements. 


If the parameters do not match as specified, you can configure Access Manager to prompt for 
additional authentication. 


For example, you have selected Screen Resolution, User Agent, Language Set, TimeZone Offset, 
and Operating System parameters in the rule. You have configured the following match conditions: 


Screen resolution: Individual 


Language Set, User Agent, TimeZone Offset, and Operating System Parameters: Parameter 
Set 


Parameter Set Match: 75% 


When the user logs in the first time, Access Manager prompts for additional authentication. After the 
successful first authentication, Access Manager calculates the fingerprint for that user and saves it for 
later usage. When the user logs in the next time, Access Manager calculates the device fingerprint of 
the device the user has used in this login attempt and compares it with the stored fingerprint. To meet 
the rule condition, screen resolution and at least any three parameters out of Language Set, User 
Agent, TimeZone Offset, and Operating System Parameters must match. 
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6.4 


Configuring a Device Fingerprint Rule 


Only one Device Fingerprint rule is allowed per Access Manager setup. If you make any change in 
the Device Fingerprint rule, the change is applicable to all risk policies that use this rule. 


Perform the following steps to configure a Device Fingerprint rule: 


1 Click Policies > Risk-based Policies > Rules > New. 
2 Click the Create Rule icon. 
3 Specify a name for the rule and then select Device Fingerprinting Rule in Rule Definition. 
4 Specify the following details: 
¢ Valid for: Specify the number of days for which you want to use the stored fingerprint. 
¢ Store Fingerprint in: Select any one of the following options: 
¢ Browser: To store the fingerprint in the browser cache on the device. 


¢ Server: To store the fingerprint in the configured risk-database. You can use this option 
only in risk-based post-authentication scenarios. To store the fingerprint in risk- 
database, you must enable storing the user history in the User History tab. (Policies > 
Risk-based Policies > User History). 


NOTE: Storing a fingerprint in Built-in Data Store (Bundled eDirectory) is not 
supported. 


For more information, see Section 6.2, “Understanding Device Fingerprint Parameters,” on 
page 691. 


¢ Fingerprints stored per user: Specify the number of fingerprints you want to store per user. 
This option is applicable only when you select Server to store fingerprints. The permissible 
value is 1 to 20. 
5 Click Parameter Settings if you want to modify the default settings. For information about 
parameters, see Section 6.2, “Understanding Device Fingerprint Parameters,” on page 691. 


For information about how to assign a rule to a risk-policy, see “Configuring a Risk Policy” on 
page 865. 


For information about risk-based authentication, see “Risk-based Authentication” on page 658 and 
“Risk-based Policies” on page 865. 


Configuring an Example Device Fingerprint Policy 


Let us assume that you want to associate the user's distinguished name with the device. So, that 
anyone else other than the registered user must provide additional authentication to log in. Also, if the 
user DN matches, but other parameters do not match as expected, you want to perform additional 
authentication. This can be achieved by configuring a risk policy with the Device Fingerprint rule. For 
the first time after implementing the policy, the intended user needs to provide additional 
authentication. Afterward, if the rule matches, the user does not need to authenticate twice. 


This example is applicable only for risk-based post-authentication scenarios. 
You can create a risk policy for this example as follows: 


1 Click Policies > Risk-based Policies > Risk Policy. 
2 Click the Create Risk Policy icon. 
3 Under Add Risk Policy, specify example-DFP-class as the name of this policy. 
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4 In the Assign Policy To, select Identity Server cluster, and then select an authentication class. 
You can select the class from the list of existing classes, or you can create a new class. 


NOTE: If you select an existing class, settings of the selected class are overwritten with values 
of this policy. 


5 To create a new Device Fingerprinting rule, perform the following actions: 


NOTE: You cannot have more than one Device Fingerprint rule in each Access Manager setup. 
If a rule is already configured, either use the existing rule or modify it based on the requirement. 


5a Under Policy Rules, click Actions > Create Rule. 

5b Specify a name for the rule and select Device Fingerprint Rule. 

5c Specify the number of days for which you want the fingerprint to be valid. 
5d_ In Store Fingerprint in, select Browser. 

5e Click Parameter Settings and make the following changes: 


Parameter Evaluation Type 


User DN Evaluate Individually 


To meet the rule criteria, this parameter must match 100%. 


Language Set Evaluate as a Group 


Screen Resolution To meet the rule criteria, the parameters in the group must 
match the percentage specified in Parameter Set Match. 


TimeZone Offset 


User Agent 


NOTE: For information about these parameters, see Section 6.2, “Understanding Device 
Fingerprint Parameters,” on page 691. 


5f In Parameter Set Match, specify 75%. For a rule to meet the criteria, User DN and at least 
three out of Language Set, Screen Resolution, TimeZone Offset, and User Agent must 
match. 


6 Click OK. 
7 Under Action to Perform, select If rule condition is met, then Exit with Risk Level as. 


8 Select Risk Level as Low. 


NOTE: You can also create a risk level here, and then assign it to the rule. See Step 11. 


9 In If rule condition is not met, add risk score, specify 30. 
10 Click Save. 


11 Under Risk Levels, click Actions > Add Risk Level and configure the risk levels with the 
following details: 
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Risk Level Risk Score Action 


Low Less than 30 Allow Access 


Medium Greater than or equal to 30 | Additional Authentication. 
Select a class to configure the step-up authentication. 


You can either select a class or a method to configure the 
step-up authentication. Typically, the step-up to a method 
is used when branding, overwriting of users, or a change 
of user store is required. If the user store of the Additional 
Authentication is the same as the risk-based 
authentication class and no additional branding is needed, 
then use a class. 


12 Configure a method for the example-DFP-class class as follows: 

12a Click Devices > Identity Servers > Edit > Local > Methods > New. 

12b Specify the name as example-DFP-method. 

12c In Class, select example-DFP-class. 

12d Deselect Identifies User. 

12e Select a user store from the list of Available User Stores and move it to User stores. 
13 Configure a contract for the example-DFP-method method. 

13a Click Local > Methods > New. 

13b Specify the name as example-DFP-contract. 

13c Select example-DFP-method in Available methods and move it to Methods. 

13d Click Next to configure a card for the contract. 


For more information, see Section 5.1.4, “Configuring Authentication Contracts,” on 
page 379. 


13e For more information about risk-based policies, see Section 5.5, “Risk-based 
Authentication,” on page 658 and Section 8.7, “Risk-based Policies,” on page 865. 


After you implement this risk policy, the following are possible scenarios: 


Scenario Risk Level Result 


When a user logs in the first time Medium Prompt for additional authentication 
because no fingerprint exists to match. 


When the fingerprint matches completely Low Allow Access 


When individual parameters match, but a Medium Prompt for additional authentication 
parameter in the group does not match as 
specified in Parameter Set Match. 


When individual parameter does not match, Medium Prompt for additional authentication 
but parameters in the group match completely 


When both individual parameter and Medium Prompt for additional authentication 
parameters in the group do not match 


When the fingerprint is expired Medium Prompt for additional authentication 
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1.1 


Enabling Mobile and Web Access 


Access Manager enables you to provide web and mobile access to protected applications and 
resources through the MobileAccess feature. MobileAccess includes a configuration portion in 
Administration Console as well as the MobileAccess app for mobile devices. Configurable options in 
MobileAccess include the following: 


+ Which applications users must be able to access through appmarks 

+ Whether users can access an application through a desktop browser or a mobile device, or both 

+ What the preferred viewer for the application on the mobile device is 

+ Whether users are required to provide a PIN to use the MobileAccess app on their mobile 
device, and if so, whether they are required to re-enter the PIN after a period of inactivity 


Appmarks are essentially bookmarks for Access Manager resources. After you have configured an 
Access Manager resource, you configure one or more appmarks to enable users to access the 
resource in different ways. You can create an appmark for: 


+ Applications 

+ Bookmarks 

+ Mobile apps 

¢ Service providers 

+ Protected resources 
The applications and service providers are different from other Access Manager resources. Access 
Manager provides connectors for the different applications that you import and configure to provide a 
single sign-on experience for the users. When you import and configure a connector, Access 
Manager automatically creates an appmark for the connector. You manage and configure the 
connectors in the Applications page of Administration Console and manage and configure appmarks 


through the Appmarks page. For more information, see the Access Manager Applications 
Configuration Guide. 


The MobileAccess app that users install on their mobile devices enables them to access Access 
Manager resources from those devices. Administrators can also make the MobileAccess app 
available to users in a private corporate store. After users have installed the app and registered their 
device, they can access the resources using the assigned authentication methods. 


Administrators can deregister user mobile devices through Administration Console on the User 
Devices page. So, if a registered mobile device is lost or stolen, or an employee leaves the company, 
you can ensure that unauthorized users cannot access corporate resources. Users can also 
deregister their own mobile devices if necessary, either from their device or from the User Portal 


page. 


User Requirements for MobileAccess 


The following are the minimum requirements for users to use MobileAccess. 


The following are the supported mobile devices and versions for MobileAccess: 
+ iPhone with 9.x 
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+ iPad or iPad mini with 9.x 
+ Android phones and tablets with Lollipop 5.x 


Configuring Appmarks 


Appmarks function like bookmarks in browsers. As with bookmarks, if the resource for the appmark 
changes, you must change the appmark to match the modified source. For example, you have an 
appmark for a protected resource and the protected resource changes, you must edit your appmark 
and select the modified protected resource again to receive the changes. 


You can configure one or more appmarks for a resource. However, that appmark is specific to a 
single IDP cluster. You can also configure appmarks for users to use with only a browser. If you want 
users to use the mobile apps, you must first configure MobileAccess. For more information, see 
Section 7.3, “Configuring MobileAccess,” on page 701. 


When you configure an appmark, you specify whether you want the application to launch in a desktop 
browser or on a supported mobile device, or both. If you configure a single appmark to display in both 
a desktop browser and on a mobile device, the appmark will have the same name, but you can 
customize the icons so they are different. Appmarks offer significant flexibility, enabling you to 
customize your users’ experience using different view options and variables. 


When you configure a new appmark to display on a mobile device, the user must do a refresh on the 
application page on the mobile device before the appmark appears. 


To create an appmark: 


1 Log in as an administrator to Administration Console. 
2 In Administration Console Dashboard under Administration Tasks, click Appmarks. 


3 (Conditional) If you have not already configured an Access Manager resource, create a 
resource, such as a service provider or a protected resource. 


4 in the Cluster field, select the appropriate IDP cluster that hosts the protected resource. 
If you have only one IDP cluster, Administration Console automatically selects that IDP cluster. 
5 Click the plus sign (+) to create an appmark. 


6 Create a new appmark using the information located in, Section 7.2.2, “Understanding 
Appmarks Options,” on page 699. 


7 Click Save. 
Repeat this process for each appmark you want to create. In order for the mobile appmark to work, 


you must configure MobileAccess. For more information, see Section 7.3, “Configuring 
MobileAccess,” on page 701. 


Creating Multiple Appmarks for an Application 


Application connectors can have multiple appmarks. For example, you might create several 
appmarks for different Office 365 or Salesforce applications. You can create a new appmark, or you 
can duplicate an existing appmark to save time, especially if you want to create several appmarks 
and just change one or two options on each one. 


To duplicate a new appmark: 


1 Log in as an administrator to Administration Console. 
2 In Administration Console Dashboard under Administration Tasks, click Appmarks. 
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3 Click the menu in the upper right corner on the appmark you want to copy, then click Duplicate. 


4 Edit the Name field because it is pre-populated with COPY_$(DisplayName). You have the 
following options: 


+ You can accept this default name. (However, note that “COPY_” will be part of the name.) 
+ You can change the display name by manually editing the text. 


5 Specify whether the application must be accessible from a desktop browser or a mobile device, 
or both, and complete the appropriate fields. For more information about available options, see 
Section 7.2.2, “Understanding Appmarks Options,” on page 699. 


6 Click Save. 


7.2.2 Understanding Appmarks Options 


You configure appmarks in Administration Console Dashboard under Administration Tasks > 
Appmarks. On each appmark that you create, there is a menu on the upper right corner that allows 
you to edit, duplicate, or delete the appmark. Clicking Edit or clicking the appmark allows you to edit 
the appmark. Clicking the plus sign (+) at the top of the page, allows you to create a new appmark. 
When you create or duplicate an appmark, the following options are available. 


Table 7-1 Appmark Options 


Option Description 


Name The display name for the appmark. If you want different display names for the 
appmark on the desktop browser page and on mobile devices, you must create 
a copy of the appmark and change the name. 


Description The description appears as hover text that users see for the appmark on the 
User Portal page. 


Change Image The image that Access Manager uses for the appmark for all platforms, unless 
you override this image with another image when configuring the different 
platforms. The maximum image size is 200 x 200 pixels and the ideal image 
size is 100 x 100 pixels. You can use an image from the Image Gallery or upload 
your own image. 


Roles (Optional) The Access Manager role that the users must have in order to see 
the appmark. If you do not select a role, all users can see the appmark on the 
User Portal page. If you add a role, only users with that role can see the 
appmark. If you add multiple roles, users in any of those roles can see the 
appmark. For example, if you add Sales and Managers, the users must be in 
Sales or Managers, not Sales and Managers, to see the appmark. 
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Option 


Type 


Enable 


Desktop 


Enabling Mobile and Web Access 


Description 


The Access Manager resource type that the appmark represents. There are 
many different types of resources: 


+ Bookmark: The URL of a website or document. 


+ Mobile App: The URL that launches the application on the mobile device. 
When the user opens the MobileAccess app on the mobile device and taps 
the appmark, MobileAccess opens the mobile app itself. 


¢ Service Provider (SAML2 Application): The term Service Provider 
refers to any SAML 2.0 service providers that you created and configured 
prior to the Access Manager 4.3 release. The term SAML 2.0 Application 
refers to a SAML 2.0 service provider that you created and configured 
using SAML 2.0 connectors either by importing a SAML 2.0 connector 
(from file or catalog) or by converting a SAML 2.0 service provider. 


The main benefit of a SAML 2.0 Application versus a SAML 2.0 service 
provider is the ability to limit user's access to the service provider based on 
roles. The roles configured on a SAML 2.0 Application in Applications 
control user access to the application. Roles are not available for SAML 
2.0 service providers. 


Roles configured on Appmarks associated with SAML 2.0 Applications or 
SAML 2.0 service providers only affect the visibility of the appmark to the 
users. 


When you configure the connector for the application, Access Manager 
automatically creates an appmark for you. You can create additional 
appmarks for the connector. 


+ Protected Resource: A protected resource on a trusted Access Gateway 
cluster that you have created prior to creating the appmark. 


The protected resource roles control access to the protected resource, not 
the appmark roles. The appmark roles only provide visibility of the 
appmark to the users. 


Select the user platforms where the appmark will be visible. The platforms are 
Desktop, iOS, and Android. 


Allows you to override the behaviors of the desktop appmark. For example, you 
can add a different icon for the desktop appmark so it sizes differently than the 
iOS appmark. You can use an image from the Image Gallery or upload your own 
image.The options to override are: 


+ Image 


¢ URL 


Option Description 


iOS and Android. The options are the same whether you select iOS or Android. You can add a 
unique image or URL for the iOS and Android appmarks so that these appmarks 
appear differently from the desktop appmarks. 


The appmarks also have additional options not available for the User Portal 
page. 


¢ Launch with: Specifies how to launch the application on the mobile 
device. Options include the following: 


+ Chrome: When the user opens the MobileAccess app on the mobile 
device and taps the appmark, the MobileAccess app launches 
Chrome and directs it to the application. If Chrome is not installed on 
the mobile device, the user is taken to the App Store or Google Play 
to install it. 


+ Internal viewer: When the user opens the MobileAccess app on the 
mobile device and taps the appmark, the MobileAccess app opens an 
embedded HTML viewer and directs it to the application. This view is 
similar to the Safari and Chrome options, except that the user does 
not need to leave the MobileAccess window. The application opens 
within the MobileAccess app window, and the user can tap the app 
name (as defined by the administrator when configuring 
MobileAccess) on the navigation bar in the top left corner of the 
screen to go back to the app home page and easily switch to another 
protected resource. 


+ Safari (IOS only): When the user opens the MobileAccess app on a 
mobile device and taps the appmark, the MobileAccess app launches 
Safari and directs it to the application. 


+ User Choice (Android only): When the user opens the 
MobileAccess app on a mobile device and taps the appmark, the 
MobileAccess app allows the user to choose what browser launches. 


+ App Installer URL: (Optional) You can use this option if you selected the 
Mobile App type. This is the URL to install the application if it is not 
already installed on the mobile device. 


7.2.3 Managing Icons 


7.3 


Access Manager provides a set of default images you can use when creating an appmark. You can 
also upload your own images. The maximum image size is 200 x 200 pixels and the ideal image size 
is 100 x 100 pixels. 


You can delete and edit images you upload. You are not allowed to delete or edit any of the images 
that come with Access Manager. You edit or delete the images when you are creating or editing 
appmarks. 


Configuring MobileAccess 


After you have created appmarks, you must configure MobileAccess to enable users to register their 
mobile devices through the MobileAccess app (iOS or Android). Users can access the appmarks 
through a browser on a desktop or a mobile device without enabling MobileAccess. 
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NOTE: MobileAccess communicates only over an HTTPS connection. MobileAccess does not work 
with HTTP. 


To configure MobileAccess: 
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Log in as an administrator to Administration Console. 
In Administration Console Dashboard under Administration Tasks, click MobileAccess. 
Select the IDP cluster that contains the appmarks you want to enable for the MobileAccess app. 


Select Enable MobileAccess to enable users to register their devices if they have the 
MobileAccess apps installed. 


In the Device display name field, specify your company name. This name appears in the bar at 
the top of the MobileAccess app window on users’ mobile devices. 


In the Roles field, select the roles that users must be able to register their devices through the 
MobileAccess app. 


If you do not select a role, all users can register their devices through the MobileAccess app. If 
you add a role, only users with that role can register their devices through the MobileAccess app. 
If you add multiple roles, users in any of those roles can register their devices through the 
MobileAccess app. For example, if you add Sales and Managers, the users must be in Sales or 
Managers, not Sales and Managers, to register their devices through the MobileAccess app. 


In the Mobile device registration contract field, select the contract that users will see to register 
their devices through the MobileAccess apps. You can select any contracts listed. However, not 
all Access Manager contracts work with mobile devices. 


IMPORTANT: Ensure that the contract you select works with mobile devices. In general, any 
basic authentication or certificate contracts do not work on mobile devices. 


In the Methods satisfied by mobile authentication field, select the authentication methods that 
are satisfied after users have successfully registered a mobile device. 


In the Password Prompt field, select how long users can continue to use an authenticated 
password on mobile devices before re-authentication is required. 


In the PIN Prompt field, select whether users must set a PIN for the MobileAccess app on their 
mobile devices, and whether they must re-enter the PIN after a period of inactivity. You can 
change this requirement at anytime. For more information, see Section 7.6, “Understanding the 
MobileAccess PIN,” on page 704. 


Click Save. 
Repeat the procedure for each IDP cluster that contains appmarks. 


7.4 Helping Users Register Their Mobile Devices 


Users can install the MobileAccess app on a mobile device to use MobileAccess with Access 
Manager. A user can register a device with multiple providers by setting up separate accounts for 
each one. If a user registers a device with multiple providers, the user must select the account to use 
for a session from the providers listed on the device. By default, the app connects the user to the first 
provider in the list. 


As an administrator, you can provide two different ways for users to register a mobile device with 
Access Manager. 
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7.4.1 Registering iOS Devices 


There are two different ways you can provide to users to register an iOS mobile device. 


¢ Manual: Send your users an email with the URL to the IDP server including the correct port 
number. The users enter the IDP URL in the MobileAccess app by tapping the menu in the upper 
left corner of the MobileAccess app, then tap Accounts > + to enter the URL of the IDP in the 
Providers field. The URL is: 


https://IDP_server_dns_name: port 
For example: 
https://idp.acme.com: 8443 


¢ Embedded Link in Email: You can send your users the following link. When the users click the 
link, the link launches the MobileAccess app and the user is presented with the Sign In page. 
The user signs in using their corporate credentials to access the appmarks available in the 
MobileAccess app. The link is: 


comnetiqauth: //x-callback-url/register?providerUrl=https:// 
IDP_server_dns_name:port/ 


For example: 


comnetiqauth: //x-callback-url/register?providerUrl=https://idp.acme.com:8443/ 


NOTE: Email client can prevent embedded links from working. 


7.4.2 Registering Android Devices 


There are two different ways you can provider to users to register an Android device. 


¢ Manual: Send your users an email with the URL to the IDP server including the correct port 
number. The users enter the IDP URL in the MobileAccess app by tapping the menu in the upper 
right corner of the MobileAccess app, then tapping Manage Accounts > + to enter the URL of the 
IDP in the Provider field. The URL is: 


https://IDP_server_dns_name: port 
For example: 
https://idp.acme.com: 8443 


+ HTML Page with Anchor Link: You can also create an HTML page that contains an anchor link 
that users click on to have the Provider field populated for them. The format of the anchor link is: 


<html> 

<body><a href="intent://x-callback-url/register?providerUrl= https:// 
IDP_server_dns_name:port#Intent; scheme=comnetiqauth; package=com.netiq.mobileac 
cessforandroid;end;'">Register</a></body> 
</html> 


For example: 


<html> 

<body><a href="intent://x-callback-url/register?providerUrl= https:// 
idp.acme.com:8443#Intent ; scheme=comnetiqauth; package=com.netiq.mobileaccessfor 
android; end; ">Register</a></body> 
</html> 
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7.6 


Installing MobileAccess on a Mobile Device 


After you have created appmarks and enabled MobileAccess in Administration Console Dashboard, 
users must install the MobileAccess app on supported mobile devices before they can access any 
resources that have been configured for mobile access. For more information, see Access Manager 
Mobile Users Quick Start. 


Understanding the MobileAccess PIN 


Access Manager administrators can require users to set a PIN on their mobile devices as a security 
measure to prevent unauthorized users from accessing protected resources through the 
MobileAccess app. Administrators can also specify whether users must re-enter the PIN after a 
period of inactivity on the device. 


For only iOS, Access Manager allows users to use the fingerprint stored in iOS as a PIN. If you do not 
enable the option for a PIN, MobileAccess does not use the stored fingerprint. If you enable the PIN 
for MobileAccess, MobileAccess uses the stored fingerprint instead of the PIN. If a user has not 

configured the fingerprint reader for the iOS device, MobileAccess defaults to using the PIN instead. 


Users must install the MobileAccess app on the mobile device before they can set the PIN. If a PIN is 
required, the MobileAccess app prompts users to set the PIN the first time they open the app. 
Otherwise, users can set, change, or remove the PIN anytime by accessing the Settings page from 
the MobileAccess app. 


NOTE: The MobileAccess PIN is unrelated to the built-in device passcode, which is designed to 
protect other resources on the mobile device. 


Even if the administrator does not require users to set a PIN, users can optionally set a PIN on their 
device. The PIN can be different for each mobile device the user registers. The PIN is not stored 
anywhere other than on the device itself. 


Administrators can change the PIN Prompt setting anytime in Administration Console Dashboard. If 
the administrator specifies that a PIN is required after a mobile device has already been registered, 
the next time the user launches the MobileAccess app on the mobile device, MobileAccess prompts 
the user to seta PIN. The app then prompts the user for that PIN each subsequent time the user 
accesses the app. If the administrator initially requires users to set a PIN and then changes that 
requirement, users can remove the PIN from their device. However, MobileAccess does not notify 
users if a PIN is no longer required. 


Whether the Access Manager administrator requires users to set a PIN or a user chooses to set a 
PIN, by default users can enter their PIN incorrectly five times. On the fifth attempt, the application 
deregisters the mobile device and removes the current PIN. The user must then reregister the device 
and reset the PIN. For more information, see “Deregistering Your Device” in the Access Manager 
Mobile Users Quick Start. 
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Managing Mobile Devices 


Access Manager administrators can manage and deregister user mobile devices in Administration 
Console Dashboard. So, if a registered mobile device is lost or stolen, or an employee leaves the 
company, you can ensure that unauthorized users cannot access corporate resources. 


Users can also deregister their own mobile devices, either from their device or from the User Portal 
page after they log in. A mobile device that has previously been deregistered can be reregistered by 
the same user. However, for a different user to use the deregistered mobile device, the user must 
delete and reinstall the MobileAccess app on the device before reregistering the device. 


Use the information in the following sections to help you manage mobile devices: 


Deregistering Mobile Devices 


If you are logged in to Administration Console as an administrator, you have the option to search for 
and deregister devices that are registered to other users. Users can manage their own devices from 
the User Portal page after they log in. 


To deregister mobile devices: 


Log in as an administrator to Administration Console. 
In Administration Console Dashboard under Administration Tasks, click User Devices. 
Select the IDP cluster that contains the user. 
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If you want to search for the devices belonging to a particular user, enter the user name in the 
User field. 


or 
Browse the list of devices Administration Console displays. 

5 Click the Delete icon next to the device you want to deregister, then click OK on the confirmation 
message. 


After a mobile device has been deregistered, the device can be registered to a new user. However, 
the MobileAccess app on the device must first be deleted and reinstalled. For more information, see 
Section 7.7.3, “Deleting and Reinstalling the MobileAccess App on a Device,” on page 705. 


Deregistering a Mobile Device as a User 


Users who have previously registered a mobile device can deregister the device if necessary. For 
more information, see “Deregistering Your Device” in the Access Manager Mobile Users Quick Start. 


NOTE: Users can uninstall the MobileAccess app on a mobile device after the device has been 
deregistered. However, if the MobileAccess app is uninstalled without the device first being 
deregistered, the device continues to appear on the Devices page. The administrator or user can 
delete the device from the Devices page in Administration Console Dashboard. 


Deleting and Reinstalling the MobileAccess App ona 
Device 


After a mobile device has been deregistered, the MobileAccess app on the device must be deleted 
and reinstalled before a different user can reregister the device. 
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To delete and reinstall the MobileAccess app on a device: 


1 


2 


Follow the instructions to uninstall the MobileAccess app: 
+ iOS (http:/Awww.apple.com/support/iphone/assistant/application/#section_5) 
+ Android (https://support.google.com/googleplay/answer/25217687?hl=en) 


Reinstall the MobileAccess app. For more information, see “Installing the MobileAccess App” in 
the Access Manager Mobile Users Quick Start. 


Installing the Access Manager Certificate Authority 
Certificate on a Mobile Device 


You can add the Access Manager certificate authority (CA) certificate to an iOS mobile device by 
performing the following steps: 


NOTE: This procedure does not work in Chrome. 


To install a self-signed certificate on the mobile device: 


1 
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Take the Access Manager CA certificate and email it to the user who has an email account 
configured on the mobile device. Alternatively, you could put it on a web or FTP site that is 
accessible from the mobile device. 


Open the email, website or FTP site on the mobile device and tap the certificate attachment. 

In the Install Profile window, tap Install. 

Read the warning, then tap Install. 

Verify that the certificate reads Trusted with a green check mark in the Profile Installed window. 


(Conditional) If the certificate is not trusted, something is wrong with the certificate and the 
MobileAccess app will not work. Go back and try to generate the certificate again. 


Tap Done. 


8 Specify the Identity Server DNS name in the Safari address bar and ensure that there is no 


warning about an untrusted certificate. 


Changing the Branding of the User Portal Page 


Administration Console Dashboard allows you to change the default branding of the User Portal page 
so your users see only your company’s information. To do complex customization, you can still edit 


the JSP file to make changes. For more information, see Section 4.1.3, “Customizing Identity Server,’ 


on page 254. 


To make simple branding changes on the User Portal page: 


1 
2 


Log in as an administrator to Administration Console. 
In Administration Console Dashboard under Administration Tasks, click Branding. 


3 Select the appropriate IDP cluster. 


Just as appmarks are unique per IDP cluster, the branding is unique per IDP cluster. 


4 Click Change Image, then either select an image from the image gallery or upload your own 


image. 


5 In the text field, specify a name that is appropriate for your company. 
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6 Specify a color name, an RGB value, or a HEX number for the appropriate color for the banner. 
For example, enter #ffffff, Aquamarine, or rgb(26,155,130). 


For a full list of the supported color names, see HTML Color Names. 


For a solid background color, leave the Right Background Color field blank. You can also use a 
valid CSS background style syntax in either background definition field, but not both fields. For 
example, enter linear-gradient (to right, red, blue). 


IMPORTANT: To properly brand the MobileAccess applications, use only one HEX number for 
each color and no advanced CSS features. 


7 Click Save. 
8 Repeat the procedure for each IDP cluster. 


To change the User Portal page beyond the branding changes you must perform manual steps and 
customization of .jsp files. For more information, see Section 4.1.3, “Customizing Identity Server,” 
on page 254. 
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Access Manager Policies 


Policies provide the authorization component of Access Manager. The administrator of Identity 
Server can use policies to define how properties of a user’s authenticated identity map to the set of 
active roles for the user. This role definition serves as the starting point for role-based authorization 
policies of Access Gateway. Additionally, you can define authorization policies to control access to 
protected resources based on user and system attributes other than assigned roles. 


Policies are very flexible. For example, you can set up a policy that allows or denies access to a 
protected website, depending on user roles (Such as employee or manager), the value of an LDAP 
attribute, or the user’s IP address. 


Access Gateway includes an Embedded Service Provider agent that interacts with Identity Server to 
provide authentication, policy decision, and policy enforcement. For Web application servers, Access 
Gateway provides the ability to inject the user’s roles into HTTP headers to allow integration with the 
web server’s authorization processes. 


This section describes how Access Manager uses policies to assign roles to control access and to 
enable single sign-on to resources that require credentials. 


This section includes the following topics: 


¢ Section 8.1, “Understanding Policies,” on page 709 

¢ Section 8.2, “Role Policies,” on page 721 

¢ Section 8.3, “Authorization Policies,” on page 760 

¢ Section 8.4, “Identity Injection Policies,” on page 810 

¢ Section 8.5, “Form Fill Policies,” on page 831 

¢ Section 8.6, “External Attribute Source Policies,” on page 860 


¢ Section 8.7, “Risk-based Policies,” on page 865 


Understanding Policies 


Policies are logical and testable rules to maintain security and consistency within your Access 
Manager infrastructure. You can specify activation criteria, deactivation criteria, temporal constraints 
(such as time of day or subnet), identity constraints (such as user object attribute values), and 
additional separation-of-duty constraints. Identity information can come from any identity source 
(such LDAP, an Identity Vault, or a directory) or from Access Manager's Identity Server, which 
provides full Liberty Alliance specification support and SAML 2.0 support. Identity is available 
throughout the determination of rights and permissions. 

¢ Section 8.1.1, “Selecting a Policy Type,” on page 710 

¢ Section 8.1.2, “Tuning the Policy Performance,” on page 710 

¢ Section 8.1.3, “Managing Policies,” on page 711 

¢ Section 8.1.4, “Managing Policy Containers,” on page 713 

¢ Section 8.1.5, “Managing a Rule List,” on page 714 

e Section 8.1.6, “Adding Policy Extensions,” on page 716 


¢ Section 8.1.7, “Enabling Policy Logging,” on page 720 
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8.1.1 


8.1.2 


Selecting a Policy Type 


Access Manager uses the policy type to define the context within which a policy is evaluated. Each 
type of policy differs in purpose, which in turn determines the conditions and actions that apply. For 
example, the conditions and actions of an Authorization policy differ from the conditions and actions 
of an Identity Injection policy. 


When you click New on the Policies page, the system displays the predefined policy types in a drop- 
down list. Each policy type represents the set of conditions and actions that are available. You then 
configure rules to determine user roles, make decision requests, and enforce authorization decisions. 
You can also set up policies with no conditions, allowing actions to always take place. As policies and 
conditions become complex, it can be simpler and more manageable to design policies with 
conditions that deny or restrict access to large groups of users, rather than setting up policies that 
permit access to certain users. 


Access Manager has the following policy types: 


+ Access Gateway: Authorization: This policy type is used to permit or deny access to protected 
resources, such as web servers. After you have set up the protected resource, you use the 
policy rules to define how you want to restrict access. For example, if a user is denied access to 
a resource, you can use the policy to redirect them to a URL where they can request access to 
the resource. 


+ Access Gateway: Identity Injection: This policy type evaluates the rules for Identity Injection, 
which retrieves identity data from a data source (user store) and forwards it to Web applications. 
Such a policy can enable single sign-on. After the user has authenticated, the policy supplies the 
information required by the resource rather than allowing the resource to prompt the user for the 
information. 


+ Access Gateway: Form Fill: This policy type creates a policy that automatically fills in the 
information required in a form, after the form is filled the first time. Use this policy to configure 
single sign-on for resources that require form data and for injecting JavaScript to an HTML page. 
You can also use this policy for injecting JavaScript to HTML pages. 


¢ Identity Server: Roles: This policy type evaluates rules for establishing the roles of an 
authenticated user. Roles are generated based on policy statements each time a user 
authenticates. Roles are placed into an Authentication Profile, which can be used as input in 
policies for Authorization or Identity Injection. 


¢ Identity Server: External Attribute Source: This policy type is used to create a policy that 
retrieves the attributes from external sources. 


Tuning the Policy Performance 


Authorization and Identity Injection policies allow you to select conditions, one of which is Roles. If 
you have thousands of users accessing your resources, you might want to design most of your 
policies to use roles. Roles are evaluated when a user logs in, and the roles assigned to the user are 
cached as long as the session is active. When the user accesses a resource protected by a policy 
that uses role conditions, the policy can be immediately evaluated because the user's role values are 
available. This is not true for all conditions; the values for some conditions must be retrieved from the 
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user store. For example, if the policy uses a condition with an LDAP attribute, the user’s value must 
be retrieved from the LDAP user store before the policy can be evaluated. On a system with medium 
traffic, this delay is not noticed. On a system with high traffic, the delay might be noticeable. 


However, you can design your policies to have the same results without retrieving the LDAP attribute 
value at resource access. You can create a Role policy for the LDAP attribute and have users 
assigned to this role at authentication when they match the attribute value requirements. When users 
access resources, they gain immediate access or are immediately denied access because their role 
assignments are cached. 


If the same LDAP attribute policy is used to grant access to multiple resources, chances that a user 
notices a delay are minimal. The first time a policy is evaluated for a user, the data required for the 
policy is cached and is therefore immediately available the next time it is requested. 


Another option available for LDAP, Credential Profile, Liberty User Profile, and Shared Secret 
attributes is to have the attribute values sent with the assertion at authentication. You configure an 
attribute set for the attributes, and then configure the service provider for these attributes. For more 
information, see “Configuring the Attributes Sent with Authentication” on page 188. 


As you design your policies, experiment and find the type that works best for your network and your 
customers. 


8.1.3 Managing Policies 


1 In Administration Console Dashboard, click Policies > Policies. 
2 Inthe Policy Container drop-down list, select the container. 
If you have not created any containers, only the Master_Container is available in the list. 

3 You can perform the following tasks from this page: 

+ “Creating Policies” on page 711 

¢ “Sorting Policies” on page 712 

+ “Deleting Policies” on page 712 

+ “Renaming or Copying a Policy” on page 712 

¢ “Importing and Exporting Policies” on page 712 

+ “Refreshing Policy Assignments” on page 712 


8.1.3.1 Creating Policies 


Before creating policies, you need to design your policy strategy. For example, if you are going to use 
role-based access, you need to decide which roles you need and which roles allow access to your 
protected resources. Roles, which are used by Authorization policies that grant and deny access, 
need to be created first. If you have already created the roles and assigned them to users in your 
LDAP user store, you can use the values of your role attributes in the Authorization policies rather 
than using Access Manager roles. 


To create a policy, see the following sections: 
¢ Chapter 8.2, “Role Policies,” on page 721 
¢ Chapter 8.3, “Authorization Policies,” on page 760 
¢ Chapter 8.4, “Identity Injection Policies,” on page 810 
¢ Chapter 8.5, “Form Fill Policies,” on page 831 
+ Chapter 8.6, “External Attribute Source Policies,” on page 860 
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8.1.3.2 


8.1.3.3 


8.1.3.4 


8.1.3.5 


8.1.3.6 


Sorting Policies 


Policies can be sorted by name and by type. On the Policies page, click Name in the Policy List, and 
the policies are sorted alphabetically by name. To sort alphabetically by type, click Type in the Policy 
List. 


You can also use containers to organize your policies. For more information, see Section 8.1.4, 
“Managing Policy Containers,” on page 713. 


Deleting Policies 


A policy cannot be deleted as long as a resource is configured to use the policy. This means that you 
must remove the policy from all protected resources for Access Gateway. 


Roles can be used by Authorization, Form Fill, and Identity Injection policies. Before you can delete a 
Role policy, you must remove any reference to the role from all other policies. 


Renaming or Copying a Policy 


Copy: To copy a policy, select a policy, click Copy, then click OK. The new policy is named “Copy of 
... This is useful when you are creating multiple policies that require only minor variations to make 
them unique. You must rename the policy after making these modifications. 


Rename: To rename a policy, select a policy, click Rename, specify a new name, then click OK. 


Importing and Exporting Policies 


Policies that are created in Administration Console can be exported and used in another 
Administration Console that is managing a different group of Access Gateways and other devices. 
Each policy type has slightly different import requirements. See the following: 


¢ Section 8.2.8, “Importing and Exporting Role Policies,” on page 760 

¢ Section 8.3.5, “Importing and Exporting Authorization Policies,” on page 809 

¢ Section 8.4.10, “Importing and Exporting Identity Injection Policies,” on page 829 
¢ Section 8.5.5, “Importing and Exporting Form Fill Policies,” on page 855 


Refreshing Policy Assignments 


If you have made changes in policy assignments that are not reflected on the page, click Refresh 
References. This action can take a while to complete if you have numerous policies and have 
assigned them to protect numerous resources. Administration Console needs to verify the 
configuration of each device. 


If you have made changes in policy assignments that are not reflected on the page, click Refresh 
References. This action can take a while to complete if you have numerous policies and have 
assigned them to protect numerous resources. Administration Console needs to verify the 
configuration of each device. 
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8.1.3.7 


8.1.4 


Viewing Policy Information 


The Policy List table displays the following information about each policy: 


Column 
Name 


Type 


Used By 


Extensions Used 


Description 


Description 
Displays the name of the policy. To modify a policy, click its name. 


Specifies the type of policy (Authorization, Identity Injection, Roles, or Form Fill) and 
the type of resource that can use it (Identity Server or Access Gateway). 


Displays the name of Access Gateway or Identity Server configuration that the 
policy is assigned to. If the policy is unassigned, this column has no value. 


If the policy is assigned to a protected resource, click the down-arrow button to view 
the names of the resources it has been assigned to. 


Specifies whether the policy uses any extensions. If none has been used, this 
column has no value. 


Displays a description of the policy. If no description has been specified, this 
column has no value. 


Managing Policy Containers 


You use policy containers to store and organize policies, similar to how you organize files in folders. 
The Master_Container is a permanent policy container, but you can use the Containers tab to create 


new containers. 


A policy container can hold up to 500 policies. When you reach that limit, you must create another 
container to add, copy, or import policies. For performance and for ease in finding a policy, you might 
want to limit a container to 200 or fewer policies. Policies in a container can be sorted by name and 
type, to aid you in finding a particular policy. 


If you have only one administrator configuring and managing policies, you can create additional policy 
containers to help you keep policies organized. If you have multiple administrators creating policies, 
you can create a container for each administrator to use. This allows multiple administrators to modify 
policies at the same time. When an administrator opens a policy in a container, the container is 
locked, which prevents other administrators from modifying any policies in that container until 
changes are applied or canceled. 


1 In Administration Console Dashboard, click Policies >Containers. 


2 On the Containers page, click New. 


3 Name the policy container, then click OK. 


4 Click Close. 


After you add a policy container, the system displays it in the Policy Container drop-down list on 
the Policy List page. 


You must delete all the policies in a policy container before you can delete the policy container. 


1 Select the check box of the policy container. Click Delete.A Confirm dialog box displays a 
message "Number of Containers selected: 1, Delete selected Containers?" 


2 Click Ok to continue or Cancel to close the window 
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8.1.5 


8.1.5.1 


Managing a Rule List 


You configure rules to create a policy. The rules collectively represent a desired course of action 
when the required conditions are met, such as denying entry-level employees access to a secure 
website, and permitting access for employees who have a role of Manager. 


When the system evaluates the policy conditions, it begins with the rule with the highest priority and 
evaluates the conditions, starting with the first condition group in the rule. Each rule contains one or 
more conditions and one or more actions. If a rule’s conditions are met, the rule’s action is performed. 
For some policy types, the performance of any rule’s action terminates the policy evaluation. With 
Authorization policies, for example, after the policy has determined that a user is either permitted or 
denied access to a resource, there is no reason to evaluate the policy further. However, a Role policy 
might identify multiple roles to which a user belongs. In this case, each rule of the policy must be 
evaluated to determine all roles to which the user belongs. 


IMPORTANT: The interface for the policy engine is designed for flexibility. It does not protect you 
from creating rules that do nothing because they are always true or always false. For example, you 
can set up a condition where Client IP is equal to Client IP, which is always true. You are responsible 
for defining the condition so that it does a meaningful comparison. 


To manage the list of rules for a policy: 


1 In Administration Console Dashboard, click Policies > Policies. 
2 Select the container. 
3 Click the name of the policy. 
4 in the Rule List section, select one of the following: 
New: To create a new rule, click New. 


You use multiple rules to coordinate how a policy operates, and the behavior varies according to 
the policy type. To understand how multiple rules are evaluated, see the following: 


¢ “Rule Evaluation for Role Policies” on page 714 
+ “Rule Evaluation for Authorization Policies” on page 715 
¢ “Rule Evaluation for Identity Injection and Form Fill Policies” on page 715 


Delete: Select a rule, then click this option to delete the rule. If the policy has only one rule, you 
cannot delete the last rule. 


Copy: Select a rule, then click this option to copy a rule. To modify the copy, click the rule 
number. 


Enable: Select a rule, then click this option to enable a rule. 
Disable: Select a rule, then click this option to disable a rule. 
5 Click OK, then click Apply Changes. 


Rule Evaluation for Role Policies 


A Role policy is used to determine which role or roles a user is assigned to. However, you can specify 
only one role per rule. Role policies are evaluated when a user authenticates. Role policies do not 
directly deny or allow access to any resource, nor do they determine if a user is authenticated. A 
user's role can be used in the evaluation of an Authorization policy, but at that point the evaluation of 
the role policy has already occurred and is not directly part of the authorization process. The 
performance of an action (assigning a user to a role) does not terminate the evaluation of the policy, 
so subsequent rules in the policy continue to be evaluated. 
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8.1.5.2 


8.1.5.3 


8.1.5.4 


Rule Evaluation for Authorization Policies 


When Access Gateway discovers a rule in an Authorization policy that either permits or denies a user 
access to a protected resource, it stops processing the rules in the policy. Use the following 
guidelines in determining whether your Authorization policy needs multiple rules: 


+ Ifthe policy enforces multiple access requirements that can result in differing actions (either 
permit or deny), use separate rules to define the conditions and actions. 


¢ If you want other conditions or actions processed when a rule fails, you must create a second 
rule for the users that fail to match the conditions. 


If you create multiple rules, you can modify the order that the rules are processed. This allows you to 
create policies that contain a number of Permit rules that allow access if the user matches the rule. 
The lowest priority rule in such a policy is a Deny rule, which denies access to everyone who has not 
previously matched a Permit rule. 


IMPORTANT: If you create policies with multiple Permit rules, you must make the last rule in the 
policy a generic deny policy (a rule with no conditions and with an action of deny). This ensures that if 
the Result on Error Condition field in a rule is set incorrectly, the user matches the last rule and is 
denied access. Without this rule, a user might gain access because the user didn’t match any of the 
rules. 


You can also create a number of policies and enable multiple policies for the same protected 
resource. Rule priority determines how the enabled policies interact with each other. The rules in the 
policies are gathered into one list, then sorted by priority. The processing rules are applied as if the 
rules came from one policy. It is a personal design issue whether you create a policy with multiple 
rules or create multiple policies that you enable on a single protected resource. Either design 
produces a list of rules, sorted by priority, that is applied to the user requesting access to the 
protected resource. 


Rule Evaluation for Identity Injection and Form Fill Policies 


Rules in Identity Injection and Form Fill policies have actions, but no conditions. Because they have 
no conditions, all the rules are evaluated and the actions are performed. Identity Injection policies 
have two exceptions to this rule; they can insert only one authentication header and one cookie 
header. If you create multiple rules, each with an authentication header and a cookie header, the rule 
with the highest priority is processed and its actions performed. The actions in the second rule for 
injecting an authentication header and a cookie header are ignored. 


You cannot create multiple rules for a Form Fill policy. 


Viewing Rules 


The policy view administrators can view the information related to rules.The rules collectively 
represent a desired course of action when the required conditions are met, such as denying entry- 
level employees access to a secure website, and permitting access for employees who have a role of 
Manager. 


When the system evaluates the policy conditions, it begins with the rule with the highest priority and 
evaluates the conditions, starting with the first condition group in the rule. Each rule contains one or 
more conditions and one or more actions. If a rule’s conditions are met, the rule’s action is performed. 
For some policy types, the performance of any rule’s action terminates the policy evaluation. 
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8.1.6 


8.1.6.1 


To view the list of rules for a policy: 


In Administration Console Dashboard, click Policies > Policies. 
Select the container. 
Click the name of the policy. 
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In the Rule List section, the policy view administrator can view the following details.: 
Type: Displays the type of the policy. 

Description: Displays the description of the policy type. 

Priority: Displays the priority of the rule number to the policy type. 

Actions: Displays the actions for the policy type. 


Adding Policy Extensions 


If Access Manager does not supply the action, the data type, or the condition that you need fora 
policy, you can add a customized policy extension. For example, suppose you need a policy that 
permits access based on whether a user has a specific role which is assigned to users in an Oracle 
database. The custom extension could read the role assignments of the user from the Oracle 
database and return a string containing the role names. This data could then be used to determine 
access rights to Access Manager resources. 


For information about how to create a policy extension, see the NetIQ Access Manager 4.3 
Developer Guide. 


After a policy extension has been created, you need to perform the following tasks to use the 
extension: 


¢ “Installing the Extension on Administration Console” on page 716 


¢ “Distributing a Policy Extension” on page 718 
After you have configured the extension, you can perform the following tasks: 


¢ “Managing a Policy Extension Configuration” on page 719 


e “Viewing Extension Details” on page 720 


Installing the Extension on Administration Console 


The policy extension can be delivered as either a .jar file ora .zip file. 
+ “Uploading and Configuring a JAR File” on page 716 
+ “Importing a ZIP File” on page 718 
Uploading and Configuring a JAR File 
To install an extension, you need to have access to the . jar file and know the following information 


about the extension or extensions contained within the file: 


What you need to create + Adisplay name for the extension. 


+ A description for the extension. 
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What you need to know 


+ The policy type of the extension, which defines the policy type it can be used 
with. You must know whether it is an extension for an Access Gateway 
Authorization policy, an Access Gateway Identity Injection policy, or an Identity 
Server Role policy. 


+ The name of the Java class that is used by the extension. Each data type 
usually uses a different Java factory class. 


+ The filename of the extension. 


+ The names, IDs, and mapping type of any configuration parameters. 
Configuration parameters allow the policy engine to pass data to the extension, 
which the extension can then use to retrieve data or to evaluate a condition. 


+ The type of data the extension manipulates. 
Authorization Policy: Can be used to return the following: 
+ An action of deny, permit, or obligation. 


+ A condition that the extension evaluates and returns either true or false. 


+ Adata element that the extension retrieves and the policy can use for 
evaluating a condition. 


Identity Injection Policy: A data extension that retrieves data for injecting into a 
header. 


Identity Role Policy: Can be used to return the following: 


+ A condition that the extension evaluates and returns either true or false. 


+ Adata element that the extension retrieves which can be used in evaluating a 
condition or used to assign roles. 


External Attribute Source Policy: A data extension that retrieves attributes from 
external sources. 


If the file contains more than one extension, you need to create a configuration for each extension in 
the file. 
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Copy the . jar file to a location that you can browse to from Administration Console. 


In Administration Console Dashboard, click Policies > Extensions. 


To upload the file, click Upload > Browse, select the file, then click Open. 


(Conditional) If you want this . jar file to overwrite an existing version of the file, select 
Overwrite existing *.jar file. 


Click OK. 


The file is uploaded to Administration Console, but nothing is visible on the Extensions page until 
you create a configuration. 


To create an extension configuration, click New, then fill in the following fields: 


Name: Specify a display name for the extension. 


Description: (Optional) Specify the purpose of the extension and how it must be used. 


Policy Type: From the drop-down list, select the type of extension you have uploaded. 


Type: From the drop-down list, select the data type of the extension. 


Class Name: Specify the name of the class that creates the extension, such as 
com.acme.policy.action.successActionFactory. 
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File Name: From the drop-down list, select the . jar file that contains the Java class that 
implements the extension and its corresponding factory. This must be the file you uploaded in 
Step 3. 


7 Click OK. 


8 (Conditional) If the extension requires data from Access Manager, click the name of the 
extension. 


9 In the Configuration Parameters section, click New, specify a name and ID, then click OK. 
The developer of the extension must supply the name and ID that the extension requires. 
10 In the Mapping column, click the down-arrow, then select the required data type. 


The developer of the extension must supply the data type that is required. If the data type is a 
data string, then the developer needs to explain the type of information you need to supply in the 
text field. 


11 (Conditional) If the extension requires more than one data item, repeat Step 9 and Step 10. 
12 Click OK. 
The extension is now available for the policy type it was created for. 


13 (Conditional) If the class can be used for multiple policy types, you need to create an extension 
configuration for each policy type. 


For example, if an extension can be used for both an Identity Injection policy and a Role policy, 
you need to create an entry for both. The File Name option must contain the same value, but the 
other options must contain unique values. 


14 Continue with “Distributing a Policy Extension” on page 718. 
Importing a ZIP File 
A .zip file with an exported extension contains both the . jar file and the extension configuration. 


Copy the .zip file to a location that you can browse to from Administration Console. 
In Administration Console Dashboard, click Policies > Extensions. 
To upload the file, click Upload > Browse, select the file, then click Open. 
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(Conditional) If you want the . jar file in the import to overwrite an existing version of the file, 
select Overwrite existing *.jar file. 


5 Click OK. 
The extension is imported in Administration Console. 


6 (Conditional) If the extension requires some customizing, click the name of the extension and 
follow the instructions that came with the extension. 


7 Continue with “Distributing a Policy Extension” on page 718. 


8.1.6.2 Distributing a Policy Extension 
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To distributed the policy extension to the devices that need it: 


1 Create a policy that uses the extension: 


¢ Role Policy: To create a Role policy that uses the extension, see Section 8.2.3, “Creating 
Roles,” on page 726. 


¢ Identity Injection Policy: To create an Identity Injection policy that uses the extension, see 
Section 8.4.2, “Configuring an Identity Injection Policy,” on page 812. 
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¢ Authorization Policy: To create an Authorization policy that uses the extension, see 
Section 8.3.2, “Creating Access Gateway Authorization Policies,” on page 771. 


¢ External Attribute Source Policy: To create an External Attribute Source policy that uses 
the extension, see Chapter 8.6, “External Attribute Source Policies,” on page 860. 


2 Assign the policy to a device: 
+ Fora Role policy, enable it for an Identity Server. 


For more information, see Section 8.2.7, “Enabling and Disabling Role Policies,” on 
page 760. 


+ For an Authorization policy, assign it to a protected resource. 


For more information, see “Assigning an Authorization Policy to a Protected Resource” on 
page 133. 


+ Foran Identity Injection policy, assign it to a protected resource. 


For more information, see “Assigning an Identity Injection Policy to a Protected Resource” 
on page 134. 


¢ For an External Attribute Source policy, enable it for an Identity Server. 
For more information, see Section 8.6.1, “Enabling External Attributes Policy,” on page 860. 


IMPORTANT: Do not update the device at this time. The . jar files must be distributed before 
you update the device. 


3 Distribute the . jar files: 
3a Click Policies > Extensions. 
3b Select the extension, then click Distribute JARs. 
3c Restart Tomcat on the devices listed for reboot. 
¢ Linux: Enter the following commands: 
In Access Gateways: /etc/init.d/novell-mag restart. 
In Identity Servers: /etc/init.d/novell-idp restart. 


¢ Windows: Enter the following commands: 
net stop Tomcat7 
net start Tomcat7 


4 (Conditional) If the extension is for an Authorization policy or an Identity Injection policy, update 
Access Gateway. 


8.1.6.3 Managing a Policy Extension Configuration 


1 In Administration Console Dashboard, click Policies > Extensions. 
2 To export a policy extension, select the policy, then click Export. 


3 To delete an extension, a policy cannot be using it. Use the Used By column to determine the 
policies that are using the extension. Modify the listed policies. When the extension is no longer 
used by any policies, select the extension, then click Delete. 


4 To rename a policy extension, select the extension, click Rename, specify a new name, then 
click OK. When a policy extension is renamed and the extension is in use by a policy, the policy 
is updated. This causes the Apply Changes button to be active on the Policy List page. 
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8.1.6.4 


8.1.7 


Viewing Extension Details 


You can modify the details of an existing extension and control the information Access Manager 
provides to the extension when the data is evaluated. 
1 In Administration Console Dashboard, click Policies > Extensions. 
2 Click the name of the extension. 
You can view or modify the following details: 
Description: (Optional) Specifies the purpose of the extension and how it must be used. 


Class Name: Specifies the name of the class that creates the extension, for example 
com.acme.policy.action.successActionFactory. 


File Name: Specifies the . jar file that contains the Java class that implements the extension 
and its corresponding factory. Select the appropriate file from the drop-down list. 


3 (Conditional) Specify the Condition Parameters required by the extension. 


The documentation for the extension must tell you the number of parameters it requires and the 
data type of each parameter. You create the name and ID for the parameter, and they need to be 
unique for the extension. 


+ To add a configuration parameter, click New, enter a name (a string) and an ID (a number) 
for the parameter, then click OK. In the Mapping field, click the down-arrow, then select the 
data item from the list. The selected data is available whenever the extension class is called 
to evaluate an action, a condition, or data. 


+ To delete a configuration parameter, select the parameter, then click Delete. 
4 Click OK. 


Enabling Policy Logging 


Policy logging is expensive; it uses processing time and disk space. In a production environment, you 
must enable it only under the following types of conditions: 


+ You have created a new policy and need to verify its functionality. 
+ You are troubleshooting a policy that is not behaving as expected. 


To gather troubleshooting information, you must enable the File Logging and Echo To Console 
options in Identity Server configuration and set the Component File Logger Levels for Application to 
at least info. Then you must update Identity Server configuration and restart any Access Gateway 
Embedded Service Providers, so that the Embedded Service Providers read the logging options. See 
Section 21.3.1, “Configuring Logging for Identity Server,” on page 1038. When you have solved the 
problem, you must disable these options. 


The log file on the component that executed the policy is where you must look for logging information. 
For example, if you have an Access Gateway: Authorization error, look at the log on Access Gateway 
that executed the policy. 


For additional policy troubleshooting procedures, see Chapter 30.6, “Troubleshooting Access 
Manager Policies,” on page 1226. 
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8.2 


8.2.1 


Role Policies 


This section describes the following topics for Identity Server roles. 


e Section 8.2.1, “Understanding RBAC in Access Manager,” on page 721 

¢ Section 8.2.2, “Enabling Role-Based Access Control,” on page 725 

¢ Section 8.2.3, “Creating Roles,” on page 726 

¢ Section 8.2.4, “Example Role Policies,” on page 745 

¢ Section 8.2.5, “Creating Access Manager Roles in an Existing Role-Based Policy System,” on 
page 748 

¢ Section 8.2.6, “Mapping Roles between Trusted Providers,” on page 758 

¢ Section 8.2.7, “Enabling and Disabling Role Policies,” on page 760 

¢ Section 8.2.8, “Importing and Exporting Role Policies,” on page 760 


Understanding RBAC in Access Manager 


Role-based access control (RBAC) provides a convenient way to assign a user to a particular job 
function or set of permissions within an enterprise, to control access. As an administrator, you 
probably have defined a set of roles for your needs. Your roles might include Employee, Student, 
Administrator, Manager, and so on. You might have Web resources that you want available to all 
employees, or only to managers, as shown in Figure 8-1. 


Figure 8-1 Traditional RBAC 


Ww — Q a ———W 


Employees Protected Resource Managers 


Access Manager supports core RBAC functionality by providing user role mapping and the mapping 
of roles to resource rights and permissions. User role mapping is a primary function of a Role policy. 
Role mapping to resource rights is accomplished through Authorization policies. When creating a 
role, you assign users to the role, based on attributes of their identities. You also specify the 
constraints to place on the role. 


Figure 8-2 RBAC Using a Policy 


User Authentication Role Assignment Policy Evaluation Protected Resource 
& Enforcement 


As shown in Figure 8-2, during user authentication, the system checks the existing Role policy to 
determine which roles that a user must be assigned to. After authentication, assigned roles can be 
used as evaluated conditions of an Authorization policy. 


Java applications and Web server applications can also be configured to use roles for access control. 
For these applications you can use Access Manager to assign the users to the required roles. You 
can use Access Gateway Identity Injection policies to inject the assigned roles into the HTTP header 
that is sent to the web server. 
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8.2.1.2 


The following examples describe ways to use roles in Access Manager: 


¢ Section 8.2.1.1, “Assigning All Authenticated Users to a Role,” on page 722 
¢ Section 8.2.1.2, “Using a Role to Create an Authentication Policy,” on page 722 
¢ Section 8.2.1.3, “Using Prioritized Rules in an Authorization Policy,” on page 725 


Assigning All Authenticated Users to a Role 


The system assigns users to roles when they authenticate. The following example illustrates a Role 
policy that creates an Employee role. All authenticated users are assigned to the role of Employee, 
because it does not include any conditions (see “Creating an Employee Role” on page 746). 


Figure 8-3 Employee Role Policy 


Edit Rule: Employee - Rule 1 [2] 
Type: Identity Server: Roles 
Description: |Employee Activation Policy 
Priority: 1 {v 
Conditions Condition structure: | AND Conditions, OR groups Vv 


Condition Group 1 


New v 


No conditions in Rule 1. (Actions will always occur unconditionally. ) 


Actions 
New ¥ 


Do Activate Role 


Employee 


Changes made on this panel must be applied from the Policies Panel. 


OK Cancel 


Role assignment audit events can be created during authentication to Identity Server. You enabled 
this on the Logging page in Identity Server configuration when you enable the Login Provided or 
Login Consumed options. 


Using a Role to Create an Authentication Policy 


The simplest implementation of RBAC policies is to include roles as evaluated conditions when 
creating Authorization policies. 


Suppose you belong to a company of 300 employees, and ten of them are managers. You can assign 
all employees to an Employee role, and make it a condition of an Authorization policy with no 
restrictions. Such a policy would permit access to Web resources intended for all employees, as 
shown in the following example: 
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Figure 8-4 Employee Authorization Policy 


Edit Rule: Authorize _All - Rule 1 


Type: Access Gateway: Authorization 


Description: Allow All Employees| | 


Priority: 1 & 


Conditions Condition structure: | AND Conditions, OR groups Vv 


Condition Group 1 


Roles: [Current] v 


Comparison: String: Equals Y 


Mode: Case Sensitive w 
Value: Roles w Employee v 


Result on Condition Error: False w 


Append New Group | 


Actions 


New v 


Do Permit Y 


Changes made on this panel must be applied from the Policies Panel. 


oK | Cancel | 


For more sensitive Web resources intended only for managers, you might create a role called 
Manager. (See “Creating a Manager Role” on page 746). The Manager role might be a condition of 
an Authorization policy that denies access to any employee that has not been assigned to the 
Manager role when the user authenticated. The following example illustrates this. Notice that the 
operand for the governing condition logic is set to If Not. 
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Figure 8-5 Manager Authorization Policy 


Edit Rule: Deny_Non-Managers - Rule 1 


Type: Access Gateway: Authorization 


Description: |Deny everyone but managers 


Priority: 1 ¥ 
Conditions 


Condition structure: AND Conditions, OR groups Y 


E Condition Group 1 
New w 
B] If Not Y| Roles: [Current] ¥ 
Comparison: String : Equals v 
Mode: Case Sensitive w 


Value: Roles w Manager w 


Result on Condition Error: i 


Append New Group | 


Actions 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


After you have created the Authorization policies, you need to assign the policies to the resources 
they were designed to protect. 


See “Assigning an Authorization Policy to a Protected Resource” on page 133. 
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8.2.1.3 Using Prioritized Rules in an Authorization Policy 


In another policy example, you might create an Authorization policy for the Sales Department and set 
up a list of rules that evaluate whether a user has been assigned to one of the roles associated with 
the department, and then deny access if the user has not been assigned to any of them. 


The following image illustrates this scenario: 
Figure 8-6 Authorization Policy with Multiple Rules 
Edit Policy: Auth_For_ Sales Dept 


Type: Access Gateway: Authorization 
Description: Sales Department] 


New | Delete | Copy | Enable | Disable 


C] Rule Priority Enabled Action Description 

Fi a 1 7 Permit Sales Representative 
F 2 2 V Permit Sales Manager 

[] 3 3 V Permit Sales President 

O 4 10 A Deny Deny 


Changes made on this panel must be applied from the Policies Panel, 


OK Cancel | 


In this example, you specify a first-priority rule with a condition that allows access if a user has been 
assigned to the role of Sales Representative. You add rules for users assigned to the a role of Sales 
Manager, Sales Vice President, and so on. You then create a lowest-priority rule that contains no 
conditions, and an action of Deny. This policy denies any user who has not been assigned a Sales 
department role. When users do not meet the conditions of the rules, the user is denied access by the 
lowest-priority rule. 


For more information about using roles in Authorization policies, see Chapter 8.3, “Authorization 
Policies,” on page 760. 


8.2.2 Enabling Role-Based Access Control 


Role-based access control is used to provide a convenient way to assign a user to a particular job 
function or set of permissions within an enterprise, to control access. In Access Manager, you assign 
users to roles, based on attributes of their identity, and then associate policies to the role. 


To assign a role to users at authentication, you must enable it for Identity Server configuration. 
1 In Administration Console Dashboard, click Devices > Identity Servers > Servers > Edit > Roles. 
2 Click the role policy’s check box, then click Enable. 
3 To disable the role policy, click the role policy’s check box, then click Disable. 
4 To create a new role, click Manage Policies. 
5 After enabling or disabling role policies, update Identity Server configuration on the Servers tab. 
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Creating Roles 


To implement RBAC, you must first define all of the roles within your organization and the 
permissions attached to each role. A collection of users requiring the same access can be assigned 
to a single role. Each user can also be assigned to one or more roles and receive the collective rights 
associated with the assigned roles. Arole policy consists of one or more rules, and each rule consists 
of one or more conditions and an action. 


BW N FP 


In Administration Console Dashboard, click Policies > Policies. 

Select the policy container, then click New. 

Specify a name for the policy, then select Identity Server: Roles for the type of policy. 
Fill in the following fields: 


Description: (Optional) Describe the purpose of this rule. If your role policy contains multiple 
rules, use the description to identify the purpose of each rule. 


Priority: Specify the order in which a rule is applied in the policy, when the policy has multiple 
rules. The highest priority is 1 and 10 is the lowest. 


5 To create a condition for a policy rule, click New in the Condition Group 1 section, then select 
one of the following: 


+ 


Authenticating IDP: Specifies the identity provider that authenticated the current user. To 
use this condition, you must have set up a trusted relationship with more than one identity 
provider. For configuration information, see Authenticating IDP Condition. 


Authentication Contract: Specifies the contract used to authenticate the current user. The 
selections in this list are defined in Identity Server configuration. For configuration 
information, see Authentication Contract Condition. 


Authentication Method: Specifies the method used to authenticate the current user. For 
configuration information, see Authentication Method Condition. 


Authentication Type: Compares a selected authentication type to the authentication types 
used to authenticate the current user. For configuration information, see Authentication 
Type Condition. 


Credential Profile: Requires the user to use the specified credential for authentication. 
Only values used at authentication time are available for this comparison. For configuration 
information, see Credential Profile Condition. 


LDAP Group: Specifies a group in which the authenticating user is evaluated for 
membership. For configuration information, see LDAP Group Condition. 


LDAP OU: Specifies an OU against which the authenticating user's container is evaluated 
for containment. For configuration information, see LDAP OU Condition. 


LDAP Attribute: Specifies an attribute from the user object of an authenticated user. By 
default, the selection values include those defined for the InetOrgPerson class. For 
configuration information, see LDAP Attribute Condition. 


Liberty User Profile: Specifies any one of a number of data values that have been mapped 
to a Liberty Profile attribute. For configuration information, see Liberty User Profile 
Condition. 


Roles from Identity Provider: Specifies a role that has been assigned to the user by an 
identity provider. For configuration information, see Roles from Identity Provider Condition. 


User Store: Compares a selected user store to the user store where the current user is 
authenticated. For configuration information, see User Store Condition. 
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¢ Virtual Attribute: Specifies a virtual attribute. The virtual attribute is used to store the 
transformed attribute values in the user’s session. For configuration information, see “Virtual 
Attribute Condition” on page 741 


¢ Condition Extension: (Conditional) If you have loaded and configured a role condition 
extension, this option specifies a condition that is evaluated by an outside source. See the 
documentation that came with the extension for information about what is evaluated. 


+ Data Extension: (Conditional) If you have loaded and configured a role data extension, this 
option specifies the value that the extension retrieves. You can then select to compare this 
value with an LDAP attribute, a Liberty User Profile attribute, a Data Entry Field, or another 
Data Extension. For more information, see the documentation that came with the extension. 


NOTE: To improve the policy's performance, configure the LDAP Attributes, Credential Profile, 
and Liberty User Profile attributes to be sent with authentication. For more information, 
see“Configuring the Attributes Sent with Authentication” on page 188. 


6 (Conditional) To add multiple conditions, repeat Step 5. 


For more information about using multiple conditions in a rule, see “Using Multiple Conditions” 
on page 742. 


7 Inthe Actions section, select one of the following: 


+ Activate Role: Select this option to specify a name for the role. If you are creating a role 
that needs to be injected into an HTTP header, use the capitalization format that the web 
server expects. 


+ Activate Selected Role: Select this option to obtain the role value from an external source. 


For more information about specifying a role or roles to activate, see “Selecting an Action” on 
page 743. 


8 Click OK twice. 
9 Click Apply Changes. 


10 To enable the role for an Identity Server configuration, see Section 8.2.7, “Enabling and 
Disabling Role Policies,” on page 760. 


8.2.3.1 Selecting Conditions 


You create a role by selecting the appropriate conditions that qualify a user to be assigned to a role, 
as shown in the following image: 
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Figure 8-7 Role Policy Conditions 


Edit Rule: Employee - Rule 1 Lz] 
Type: Identity Server: Roles 
Description: 
Priority: 1 w] 
Conditions Condition structure: 


ill always occur unconditionally. ) 


Authenticating IDP 
Authentication Contract 
Authentication Method 
Authentication Type 
Credential Profile plied from the Policies Panel. 
LDAP Group 

LDAP OU 


LDAP Attribute 


Liberty User Profile 


Roles from Identity Provider 


User Store 


The following sections describe the conditions available for a Role policy: 


+ “Authenticating IDP Condition” on page 729 

+ “Authentication Contract Condition” on page 730 
+ “Authentication Method Condition” on page 732 
+ “Authentication Type Condition” on page 733 

+ “Credential Profile Condition” on page 734 

+ “LDAP Group Condition” on page 735 

+ “LDAP OU Condition” on page 736 

+ “LDAP Attribute Condition” on page 737 

¢ “Liberty User Profile Condition” on page 738 

+ “Roles from Identity Provider Condition” on page 739 
+ “User Store Condition” on page 740 

+ ‘Virtual Attribute Condition” on page 741 

+ “Condition Extension” on page 741 

+ “Data Extension” on page 741 
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Authenticating IDP Condition 


The Authenticating IDP condition allows you to assign a role based on the identity provider that 
authenticated the current user. To use this condition, you must have set up a trusted relationship with 
more than one identity provider. See Section 3.9.3, “Managing Trusted Providers,” on page 181. 


The most common way to use this condition is when you have a service provider that has been 
configured to trust two identity providers and you want to assign a role based on which identity 
provider authenticated the user. To configure such a policy: 

+ Set the Authenticating IDP field to [Current] 

¢ Set the Value field to Authenticating IDP 

¢ Select the name of an identity provider 


For the condition to evaluate to True, the identity provider specified in the policy must be the one that 
the user selected for authentication. 


Comparison: Specify how the contract is compared to the data in the Value field. Select either a 
string comparison or a regular expression: 


¢ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 
¢ Starts with: Indicates that the Authenticating IDP value must begin with the letters 
specified in the Value field. 


¢ Ends with: Indicates that the Authenticating IDP value must end with the letters specified in 
the Value field. 


+ Contains Substring: Indicates that the Authenticating IDP value must contain the letters, 
in the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the value you want to compare with the Authenticating IDP value. If you select a static 
value for the Authenticating IDP value, select Authenticating IDP and Current. If you select Current 


for the Authenticating IDP value, select Authenticating IDP, then select the name of an identity 
provider. 


Other value types are possible if you selected Current for the Authenticating IDP value. Your policy 
requirements determine whether they are useful. 
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Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Authentication Contract Condition 


The Authentication Contract allows you to assign a role based on the contract the user used for 
authentication. Identity Server has the following default contracts: 


Name URI 

Name/Password - Basic basic/name/password/uri 
Name/Password - Form name/password/uri 

Secure Name/Password - Basic secure/basic/name/password/uri 
Secure Name/Password - Form secure/name/password/uri 


To configure other contracts for your system, click Devices > Identity Servers > Edit > Local > 
Contracts. 


The most common way to use this condition is to select [Current] for the Authentication Contract 
field and to select Authentication Contract and the name of a contract for the Value field. 


To specify an Authentication Contract condition, fill in the following fields: 


Authentication Contract: To compare the contract that the user used with a static value, select 
Current. To compare a static value with what the user used, select a contract from the list. 


If you have created more than one Identity Server configuration, select the configuration, then select 
the contract. The name of the contract is displayed. When you select this name, the configurations 
that contain a definition for this contract are highlighted. 


For example, the following policy has selected Name/Password - Basic as the contract. 


Condition Group 1 


New w 


If x Authentication Contract: : Name/Password - Basic w a 


Comparison: String : EqSelect Authentication Contract |x] 


Mode: Case Sens] [Current] 


Value: Authentic! idp-43.amlab.net > 
Result on Condition Error: False w idp-51.amlab.net > 


Append New Group | 


Two Identity Server configurations have been defined (idp-43.amlab.net and idp-51.amlab.net). Both 
configurations are highlighted because Name/Password - Basic is a contract that is automatically 
defined for all Identity Server configurations. 


If the contract you are selecting for a condition is a contract with ORed credentials, you need to use 
multiple conditions to set up a rule. See “Creating a Rule for a Contract with ORed Credentials” on 
page 747. 
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Comparison: Specify how the contract is compared to the data in the Value field. Select either a 
string comparison or a regular expression: 


+ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the Authentication Contract value must begin with the letters 
specified in the Value field. 


+ Ends with: Indicates that the Authentication Contract value must end with the letters 
specified in the Value field. 


¢ Contains Substring: Indicates that the Authentication Contract value must contain the 
letters, in the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


¢ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


¢ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the value you want to compare with the Authentication Contract value. If you select a 
static value for the Authentication Contract value, select Authentication Contract and Current. If you 
select Current for the Authentication Contract value, select Authentication Contract, then select the 
name of a contract. 


Other value types are possible if you selected Current for the Authentication Contract value. For 
example: 


+ You can select Data Entry Field. The value specified in the text box must be the URI of the 
contract for the conditions to match. For a list of these values, click Devices > Identity Servers > 
Edit > Local > Contracts. 


¢ If you have defined a Liberty User Profile attribute for URI of the authentication contract, you can 
select Liberty User Profile, then select the attribute. 


+ If you have defined an LDAP attribute for URI of the authentication contract, you can select 
LDAP Attribute, then select the attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 
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Authentication Method Condition 


The Authentication Method allows you to assign a role based on the method the user used for 
authentication. 


Authentication Method: To compare the method that the user used with a static value, select 
Current. To compare a static value with what the user used, select a method from the list. 


If you have created more than one Identity Server configuration, select the configuration, then select 
the method. The name of the method is displayed. When you select this name, the configurations that 
contain a definition for this method are highlighted. 


Comparison: Specify how the method is compared to the data in the Value field. Select either a 
string comparison or a regular expression: 


+ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the Authentication Method value must begin with the letters 
specified in the Value field. 


+ Ends with: Indicates that the Authentication Method value must end with the letters 
specified in the Value field. 


¢ Contains Substring: Indicates that the Authentication Method value must contain the 
letters, in the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the value you want to compare with the Authentication Method value. If you select a 
static value for the Authentication Method value, select Authentication Method and Current. If you 
select Current for the Authentication Method value, select Authentication Method, then select the 
name of a method. 


Other value types are possible if you selected Current for the Authentication Method value. Your 
policy requirements determine whether they are useful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 
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Authentication Type Condition 


The Authentication Type condition allows you to assign a role based on the authentication types used 
to authenticate the current user. The [Current] selection represents the current set of authentication 
types used to authenticate the user. The other selections represent specific authentication types that 
can be used to compare with [Current]. The Authentication Type condition returns true if the selected 
Authentication Type is contained in the set of Authentication Types for [Current]. For example, if the 
current user was required to satisfy the Authentication Types of Basic and SmartCard, then a 
selected Authentication Type of either Basic or SmartCard would match. 


Authentication Type: To compare the type that the user used with a static value, select Current. To 
compare a static value with what the user used, select a type from the list. 


Comparison: Specify how the type is compared to the data in the Value field. Select either a string 
comparison or a regular expression: 


+ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the Authentication Type value must begin with the letters 
specified in the Value field. 


¢ Ends with: Indicates that the Authentication Type value must end with the letters specified 
in the Value field. 


¢ Contains Substring: Indicates that the Authentication Type value must contain the letters, 
in the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


¢ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the value you want to compare with the Authentication Type value. If you select a 
static value for the Authentication Type value, select Authentication Type and Current. If you select 
Current for the Authentication Type value, select Authentication Type, then select a type. 


Other value types are possible if you selected Current for the Authentication Type value. Your policy 
requirements determine whether they are useful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 
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Credential Profile Condition 


The Credential Profile condition allows you to assign a role based on the credentials the user entered 
when authenticating to the system. Only values used at authentication time are available for this 
comparison. 


To set up the matching for this condition, fill in the following fields: 


Credential Profile: Specify the type of credential your users are using for authentication. If you have 
created a custom contract that uses a credential other than the ones listed below, do not use the 
Credential Profile as a Role condition. 


+ LDAP Credentials: If you prompt the user for a username, select this option, then select LDAP 
User Name (the cn of the user) or LDAP User DN (the fully distinguished name of the user), or 
LDAP Password. 


The default contracts assign the cn attribute to the Credential Profile. If your user store is an 
Active Directory server, the SAMAccountName attribute is used for the username and stored in 
the cn field of the LDAP Credential Profile. 


+ X509 Credentials: If you prompt the user for a certificate, select this option, then select one of 
the following: 


+ 


+ 


+ 


X509 Public Certificate Subject: Retrieves the subject field from the certificate, which can 
match the DN of the user, depending upon who issued the certificate. 


X509 Public Certificate Issuer: Retrieves the issuer field from the certificate, which is the 
name of the certificate authority (CA) that issued the certificate. 


X509 Public Certificate: Retrieves the entire certificate, Base64 encoded. 
X509 Serial Number: Retrieves the serial number of the certificate. 


¢ SAML Credential: If your users authenticate with a SAML assertion, select this option. 


Comparison: Select one of the following types: 


¢ Comparison: String: Specifies that you want the values compared as strings and indicates how 
you want the string values compared. Select one of the following: 


+ 


+ 


Equals: Indicates that the values must match, letter for letter. 


Starts with: Indicates that the Credential Profile value must begin with the letters specified 
in the Value field. 


Ends with: Indicates that the Credential Profile value must end with the letters specified in 
the Value field. 


Contains Substring: Indicates that the Credential Profile value must contain the letters, in 
the same sequence, as specified in the Value field. 


¢ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 
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Multi-Line 
Unicode 
Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the second value for the comparison. Select one of the following data types: 


+ LDAP Attribute: If you have an LDAP attribute that corresponds to the Credential Profile you 
have specified, select this option and the attribute. 


¢ Liberty User Profile: If you have a Liberty User Profile attribute that corresponds to the 
Credential Profile you have specified, select this option and the attribute. 


¢ Data Entry Field: Specify the string you want matched. Be aware of the following requirements: 


¢ If you selected LDAP User DN as the credential, you need to specify the DN of the user in 
the Value text box. If the comparison type is set to Contains Substring, you can match a 
group of users by specifying a common object that is part of their DNs, for example 
ou=sales. 


¢ If you selected X509 Public Certificate Subject as the credential, you need to specify all 
elements of the Subject Name of the certificate in the Value text box. Separate the elements 
with a comma and a space, for example, o=novell, ou=sales. If the comparison type is 
set to Contains Substring, you can match a group of certificates by specifying a name that 
is part of the Subject Name, for example ou=sales. 


Other values are possible. Your policy requirements determine whether they are useful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


LDAP Group Condition 


The LDAP Group condition allows you to assign a role based on whether the authenticating user is a 
member of a group. The value, an LDAP DN, must be a fully distinguished name of a group. 


LDAP Group: Select [Current]. 
Comparison: Specify how you want the values compared. Select one of the following: 
+ LDAP Group: Is Member of: Specifies that you want the condition to determine whether the 
user is member of a specified group. 
+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 


regular expressions. 


Mode: If you selected Regular Expression: Matches as the comparison type, select one or more of 
the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
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Value: Specify the second value for the comparison. If you select LDAP Group > Name of Identity 
Server Configuration > User Store Name, you can browse to the name of the LDAP group. 


If you have more than 250 groups in your tree, you are prompted to enter an LDAP query string. In 
the text box, you need to add only the <strFilter> value for the query. For example: 


<strFilter> Value Description 


admin* Returns all groups that begin with admin, such as 
adminPR, adminBG, and adminWTH. 


*test Returns all groups that end with test, such as doctest, 
softtest, and securtest. 


*low* Returns all groups that have “low” in the name, such 
as low, yellow, and clowns. 
For more information about the <strFilter> parameter, see RFC 2254 “LDAP Search Filter.” 


If you select Data Entry Field as the value, you can specify the DN of the group in the text field. For 
example: 

cn=managers, cn=users, dc=bcf2, dc=provo, dc=novell, dc=com 

cn=manager, o=novell 

Other values are possible. Your policy requirements determine whether they are useful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


LDAP OU Condition 


The LDAP OU condition allows you to assign a role based on a comparison of the DN of an OU 
against the DN of the authenticated user. If the user's DN contains the OU, the condition matches. 


LDAP OU: Select [Current]. 
Comparison: Specify how you want the values compared. Select one of the following: 
+ Contains: Specifies that you want the condition to determine whether the user is contained by a 
specified organizational unit. 
+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 
Mode: Select the mode appropriate for the comparison type. 
+ Contains: Select whether the user must be contained in the specified OU (One Level) or 
whether the user can be contained in the specified OU or a child container (Subtree). 
+ Comparison: Regular Expression: Matches: Select one or more of the following: 
Canonical Equivalence 
Case Insensitive 
Comments 


Dot All 
Multi-Line 
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Unicode 
Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the second value for the comparison. If you select LDAP OU > Name of Identity 
Server Configuration > User Store Name, you can browse to the name of the OU. 


If you have more than 250 OUs defined in your tree, you are prompted to enter an LDAP query string. 
In the text box, you need to add only the <strFilter> value for the query. For example: 


<strFilter> Value Description 


admin* Returns all OUs that begin with admin, such as 
adminPR, adminBG, and adminWTH. 


*test Returns all OUs that end with test, such as doctest, 
softtest, and securtest. 


*low* Returns all OUs that have “low” in the name, such as 
low, yellow, and clowns. 


For more information about the <strFilter> parameter, see RFC 2254 “LDAP Search Filter.” 

If you select Data Entry Field, you can specify the DN of the OU in the text field. For example: 
cn=users, dc=bcf2, dc=provo, dc=novell, dc=com 

ou=users, o=novell 


If you have defined a Liberty User Profile or an LDAP attribute for the OU you want to match, select 
this option, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


LDAP Attribute Condition 


The LDAP Attribute condition allows you to assign a role based on a value in an LDAP attribute 
defined for the inetOrgPerson class or any other LDAP attribute you have added. You can have the 
user's attribute value retrieved from your LDAP directory and compared to a value of the following 


type: 
¢ Roles from an identity provider 
+ Authenticating IDP or user store 
+ Authentication contract, method, or type 
¢ Credential profile 
+ LDAP attribute, OU, or group 
¢ Liberty User Profile attribute 
¢ Static value in a data entry field 


To set up the matching for this condition, fill in the following fields: 
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LDAP Attribute: Specify the LDAP attribute you want to use in the comparison. Select from the listed 
LDAP attributes. To add an attribute that isn’t in the list, click New LDAP Attribute, then specify the 
name of the attribute. 


Comparison: Specify how you want the values compared. All data types are available. Select one 
that matches the value type of your attribute. 


Mode: Select the mode, if available, that matches the comparison type. For example, if you select to 
compare the values as strings, you can select either a Case Sensitive mode or a Case Insensitive 
mode. 


Value: Specify the second value for the comparison. All data types are available. For example, you 
can select to compare the value of one LDAP attribute to the value of another LDAP attribute. Only 
you can determine if such a comparison is meaningful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Liberty User Profile Condition 


The Liberty User Profile condition allows you to assign a role based on a value in a Liberty User 
Profile attribute. The Liberty attributes must be enabled before you can use them in policies (click 
Identity Servers > Edit > Liberty > Web Service Provider, then enable one or more of the following: 
Employee Profile or Personal Profile). 


These attributes can be mapped to LDAP attributes (click Identity Servers > Edit > Liberty > LDAP 
Attribute Mapping). When mapped, the actual value comes from your user store. If you are using 
multiple user stores with different LDAP schemas, mapping similar attributes to the same Liberty User 
Profile attribute allows you to create one policy with the Liberty User Profile attribute rather than 
multiple policies for each LDAP attribute. 


The selected attribute is compared to a value of the following type: 


+ Roles from an identity provider 

+ Authenticating IDP or user store 

+ Authentication contract, method, or type 
¢ Credential profile 

+ LDAP attribute, OU, or group 

¢ Liberty User Profile attribute 

¢ Static value in a data entry field 


To set up the matching for this condition, fill in the following fields: 


Liberty User Profile: Select the Liberty User Profile attribute. These attributes are organized into 
three main groups: Custom Profile, Corporate Employment Identity, and Entire Personal Identity. By 
default, the Common Last Name attribute for Liberty User Profile is mapped to the sn attribute for 
LDAP. To select this attribute for comparison, click Entire Personal Identity > Entire Common Name > 
Common Analyzed Name > Common Last Name. 


Comparison: Select the comparison type that matches the data type of the selected attribute and the 
value. 


Mode: Select the mode, if available, that matches the data type. For example, if you select to 
compare the values as strings, you can select either a Case Sensitive mode or a Case Insensitive 
mode. 
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Value: Select one of the values that is available from the current request or select Data Entry Field to 
enter a static value. The static value that you can enter depends on the comparison type you 
selected. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Roles from Identity Provider Condition 


The Roles from Identity Provider condition allows you to assign a role based on a role assigned by 
another identity provider (Liberty, SAML 2.0, WS Federation). You configure the condition to match 
the role sent by the identity provider, then set the action to assign a new role. 


This condition uses the mapped attribute All Roles. All roles that are assigned to the user can be 
mapped to attributes and assigned to a trusted identity provider. For information about enabling All 
Roles, see Section 3.9.6, “Selecting Attributes for a Trusted Provider,” on page 187. 


For an example of how to use Roles from Identity Provider to create a Role policy, see Section 8.2.6, 
“Mapping Roles between Trusted Providers,” on page 758. For an example that explains all the 
configuration procedures required for sharing roles, see “Sharing Roles” on page 441. 


To configure a Roles from Identity Provider condition, fill in the following fields: 


Roles from Identity Provider: If you have configured your system for multiple identity providers, 
select the identity provider. If you have only one, it is selected. 


Comparison: Select one of the following types: 
+ Comparison: String: Specifies that you want the values compared as strings, and how you 
want the string values compared. Select one of the following: 
¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the Roles from Identity Provider value must begin with the letters 
specified in the Value field. 


+ Ends with: Indicates that the Roles from Identity Provider value must end with the letters 
specified in the Value field. 

¢ Contains Substring: Indicates that the Roles from Identity Provider value must contain the 
letters, in the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 
+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


¢ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 
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Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Select Data Entry Field, then specify the name of an identity provider role. Other value types 
are possible. Your policy requirements determine whether they are useful 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


User Store Condition 


The User Store condition allows you to assign a role based on the user store that was used to 
authenticate the current user. The [Current] selection represents the user store from which the user 
was authenticated. The other selections represent all of the configured user stores that can be used 
to compare with [Current]. 


For example, if the configured user stores are eDir1 and AD1 and the current user is authenticated 
from eDir1, then a selected user store of eDir1 would match and a selected user store of AD1 would 
not match. 


User Store: To compare the user store that the user used for authentication with a static value, select 
Current. To compare a static value with what the user used, select a user store from the list. 


If you have created more than one Identity Server configuration, select the configuration, then select 
the user store. The name of the user store is displayed. 


Comparison: Specify how the user store is compared to the data in the Value field. Select either a 
string comparison or a regular expression: 


¢ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the User Store value must begin with the letters specified in the 
Value field. 


+ Ends with: Indicates that the User Store value must end with the letters specified in the 
Value field. 


¢ Contains Substring: Indicates that the User Store value must contain the letters, in the 
same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Value: Specify the value you want to compare with the User Store value. If you select a static value 
for the User Store value, select User Store and Current. If you select Current for the User Store 
value, select User Store, then select the name of a user store. 


If you have created more than one Identity Server configuration, select the configuration, then select 
the user store. The name of the user store is displayed. 


Other value types are possible if you selected Current for the User Store value. Your policy 
requirements determine whether they are useful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 
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Virtual Attribute Condition 


The Virtual Attribute condition allows you to assign a role based on a value in an Virtual attribute. You 
can have the user’s attribute value retrieved from an external source and compared to a value of the 
following type: 

+ Roles from an identity provider 

¢ Authenticating IDP or user store 

+ Authentication contract, method, or type 

¢ Credential profile 

+ LDAP attribute, OU, or group 

¢ Liberty User Profile attribute 

¢ Static value in a data entry field 

¢ Virtual Attribute 


To set up the matching for this condition, fill in the following fields: 


Virtual Attribute: Specify the virtual attribute you want to use in the comparison. Select a virtual 
attribute from the list.’ 


Comparison: Specify how you want the values compared. All data types are available. Select one 
that matches the value type of your virtual attribute. 


Mode: Select the mode, if available, that matches the comparison type. For example, if you select to 
compare the values as strings, you can select either a Case Sensitive mode or a Case Insensitive 
mode. 


Value: Specify the second value for the comparison. All data types are available. For example, you 
can select to compare the value of one virtual attribute to the value of another virtual attribute. Only 
you can determine if such a comparison is meaningful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Condition Extension 


If you have loaded and configured a role condition extension, this option specifies a condition that is 
evaluated by an outside source. See the documentation that came with the extension for information 
about what is evaluated. 


Data Extension 


If you have loaded and configured a role data extension, this option specifies the value that the 
extension retrieves. You can then select to compare this value with an LDAP attribute, a Liberty User 
Profile attribute, a Data Entry Field, or another Data Extension. For more information, see the 
documentation that came with the extension. 
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Using Multiple Conditions 


The Condition structure field controls how conditions within a condition group interact with each 
other and how condition groups interact with each other. Select one of the following: 

+ “AND Conditions, OR groups” on page 742 

e “OR Conditions, AND groups” on page 742 
The following sections explain how to configure the condition groups and conditions to interact with 
each other: 

e “Using the Not Options” on page 743 

+ “Adding Multiple Conditions” on page 743 

+ “Adding New Condition Groups” on page 743 

¢ “Disabling Conditions and Condition Groups” on page 743 


AND Conditions, OR groups 


If the conditions are ANDed, the user must meet all the conditions in a condition group to match the 
profile. If the condition groups are ORed, the user must meet all of the conditions of one group to 
match the profile. This option allows you to set up two or more profiles into which a user could fit and 
be considered a match. For example, suppose you create the following Permit rule. 


The first condition group contains the following conditions: 


1. The user’s department must be Engineering. 
2. The request must come on a weekday. 


The second condition group contains the following conditions: 


1. The user’s department must be Information Services and Technology (IS&T). 
2. The request must come on a weekend. 


With this rule, the engineers who match the first condition group have access to the resource during 
the week, and the IS&T users who match the second condition group have access to the resource on 
the weekend. 


OR Conditions, AND groups 


If the conditions are ORed, the user must meet at least one condition in the condition group to match 
the profile. If the conditions groups are ANDed, the user must meet at least one condition in each 
condition group to match the profile. For example, suppose you created the following Permit rule: 


The first condition group contains the following conditions: 


1. The user’s department is Engineering. 
2. The user’s department is Sales. 


The second condition group contains the following conditions: 


1. The user has been assigned the Party Planning role. 
2. The user has been assigned the Vice President role. 
With this rule, the Vice Presidents of both the Engineering and Sales departments can access the 


resource, and the users from the Engineering and Sales department who have been assigned to the 
Party Planning role can access the resource. 
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Using the Not Options 


At the top of each condition group, there is an option that allows you to control whether the user must 
match the conditions to match the profile or whether the user matches the profile if the user does not’ 
match any of the conditions. Depending upon your selection for the Condition structure, you can 
select from the following: 

+ If/lf Not 

+ Or/Or Not 

+ And/And Not 


Conditions also have similar Not options, so that a user can match a condition by not matching the 
specified value. 


Adding Multiple Conditions 


To add another condition to a condition group, click New, then select a condition. To copy an existing 
condition, click the Copy Condition icon ‘|. New conditions are always added to the end of the 
condition group. Use the Move = buttons to order the conditions in the condition group. 


Adding New Condition Groups 


To add another condition group to the rule, click Append New Group. To copy the existing condition 
group, click the Copy Group icon [È]. New condition groups are always added to the end to the 
Conditions section. Use the Move — buttons to order the condition groups. 


Disabling Conditions and Condition Groups 


Condition groups and conditions within them can be disabled by clicking the Enabled check mark [X], 
which changes the icon to the Disabled icon |. 


You usually disable a condition or condition group when testing a new rule, and if you decide the 
condition or condition group is not needed, you can then use the Delete [X] button to delete the 
condition or condition group from the rule. Use the Move — buttons by the Delete button to move a 
condition up or down within its group. Condition groups also have Move buttons. 


Selecting an Action 


The policy action specifies the role to which the user is assigned. Roles are activated at the time the 
role policy is evaluated. Select one of the following actions: 


e “Activate Role” on page 743 
+ “Activate Selected Role” on page 744 


Activate Role 


Select Activate Role when you want to specify a name for the role. If you are creating a role that 
needs to injected into an HTTP header, use the same capitalization format as the web server expects. 
For example, if the web server expects an Employee role with an initial capital, name your role 
Employee. 


Figure 8-8 show how to assign the role of Employee to a policy. 
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Figure 8-8 Assigning a Role 


Actions 


New Action: Activate Role 


Do Activate Role i H] 
: Employee 


To use the same conditions to activate multiple roles, select Activate Role for each role you want to 
specify. 


Activate Selected Role 


Select Activate Selected Role when you want to obtain the role value from an external source. Select 
one of the following: 


¢ LDAP Attribute: If you have an LDAP attribute that is a role, select the attribute from the list. If 
the attribute is not in the list, select New LDAP Attribute to add it to the list. 


¢ LDAP Group: Activates a role based on an LDAP Group attribute. Select either [Current] or 
browse to the DN of the group by selecting Identity Server and User Store. The value for this 
option is the DN of the group. If you select [Current], the value can be a list of the groups the 
user belongs to. The [Current] value makes the DN of each group in the attribute into a role. 


If you select to browse to the DN of the group and you have more than 250 groups in your tree, 
you are prompted to enter an LDAP query string. In the text box, you need to add only the 
<strFilter> value for the query. For example: 


<strFilter> Value Description 


admin* Returns all groups that begin with admin, such as 
adminPR, adminBG, and adminWTH. 


*test Returns all groups that end with test, such as 
doctest, softtest, and securtest. 


*low* Returns all groups that have “low” in the name, such 
as low, yellow, and clowns. 


For more information about the <strFilter> parameter, see RFC 2254 “LDAP Search Filter.” 


This action does not query all the static and dynamic groups on the LDAP server to see if the 
user belongs to them, but uses the user’s group membership attribute to create the list. If you 
want to use this longer query, you need to create a policy extension. For a sample extension that 
does this, see Access Manager SDK Sample Code (https://www.netiq.com/documentation/ 
access-manager-43-developer-documentation/samplecodes/main.html). 


+ LDAP OU: Activates a role based on the Organizational Unit in the user's DN. Select either 
[Current] or browse to the DN of the OU by selecting Identity Server and User Store. The value 
for this option is the DN of the OU. 


If you select to browse to the DN of the OU and you have more than 250 OUs defined in your 
tree, you are prompted to enter an LDAP query string. In the text box, you need to add only the 
<strFilter> value for the query. For example: 
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<strFilter> Value Description 


admin* Returns all OUs that begin with admin, such as 
adminPR, adminBG, and adminWTH. 


*test Returns all OUs that end with test, such as doctest, 
softtest, and securtest. 


*low* Returns all OUs that have “low” in the name, such 
as low, yellow, and clowns. 


For more information about the <strFilter> parameter, see RFC 2254 “LDAP Search Filter.” 


¢ Liberty User Profile: If you have a Liberty attribute that is a role, select the attribute from the 
list. 


¢ Data Extension: If you have created a data extension that calculates a set of roles, select the 
extension. For information about creating such an extension, see Access Manager SDK Sample 
Code (https://www.netiq.com/documentation/access-manager-43-developer-documentation/ 
samplecodes/main.html). 


If the source contains multiple values, select the format that is used to separate the values. 
If the value is a distinguished name, select the format of the DN. 
Figure 8-9 shows how to assign an LDAP Group, cn=DocGroup,o=novell, as a role. 


Figure 8-9 Activating a Role from an External Source 


Actions 
New w 
Do Activate Selected Role HX] 
LDAP Group vw :  cn=DocGroup,o=novell w 


Multi-Value Separator; , Y DN Format; LDAP (ex, cn=jsmith,ou=Sales,o=Novell) v 


To use the same conditions to activate multiple roles from different sources, select Activate Selected 
Role for each role you want to activate. 


Example Role Policies 


The following examples describe how to create a general Employee role, a restrictive Manager role, 
and a role from a contract with ORed credentials. These roles can be used by Access Gateway in 
Identity Injection policies and by Access Gateway in Authorization policies. 

¢ Section 8.2.4.1, “Creating an Employee Role,” on page 746 

¢ Section 8.2.4.2, “Creating a Manager Role,” on page 746 


¢ Section 8.2.4.3, “Creating a Rule for a Contract with ORed Credentials,” on page 747 
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Creating an Employee Role 


The following role policy creates an Employee role. Because the role does not include conditions, all 
authenticated users are assigned to this role when they log in. This role can then be used to grant 
access to resources to all users in your user stores. 


1 


ao Aà WwW N 


In Administration Console Dashboard, click Devices > Identity Servers > Edit > Roles > Manage 
Policies. 


On the Policies page, click New. 

Select a policy type of Identity Server: Roles and specify a display name, such as Employee. 
Click OK. 

On the Edit Policy page, specify a description in the Description field. 


It is important to use this field to keep track of your roles and policies. The policy feature is 
powerful, and your setup can be as large and complex as you want it to be, with a potentially 
unlimited number of conditions and choices. This description is useful to help keep track of 
various role and policy configurations. 


Ensure that the Condition Group 1 section has no conditions, so that all users who authenticate 
match the condition. 


7 Inthe Actions section, click New > Activate Role. 


13 


In the Activate Role box, type Employee, then click OK. 


If this role needs to match the name of a role required by a Java or Web application, ensure that 
the case of the name matches the application’s name. 


On the Rule List page, click OK. 

On the Policies page, click Apply Changes, then click Close. 

On the Role Policy page, select the Employee role, then click Enable. 

Click OK, then update Identity Server. 

Identity Server configuration must be updated after you enable a role. 

To create a Manager role, continue with “Creating a Manager Role” on page 746. 


Creating a Manager Role 


Because the Manager role is restrictive, role policy conditions must be specified. The Manager role is 
assigned only to the users who meet the conditions. 


1 


In Administration Console Dashboard, click Devices > Identity Servers > Edit > Roles > Manage 
Policies. 


2 On the Policies page, click New. 


3 Select a policy type of Identity Server: Roles and specify a display name (for this example, 


Manager.) 


4 Click OK. 
5 In the Conditions section, click New > Liberty User Profile. 


6 In Condition Group 1, select the conditions the user must meet: 


Liberty User Profile: Select Entire Personal Identity > Entire Common Name > Common 
Analyzed Name > Common Last Name. 


If these options are not available, you haven't enabled the Liberty attributes. Click Identity 
Servers > Edit > Liberty > Web Service Provider, then enable one or more of the following: 
Employee Profile or Personal Profile. 
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Comparison: Select how you want the attribute values to be compared. For the Common Last 
Name attribute, select String > Equals. 


Mode: Select Case Insensitive. 


Value: Select Data Entry Field and type the person’s name in the box (Smith, in this example). 
This sets up the condition that if the user has the name Smith, his or her role as Manager is 
activated at authentication. 


Result on Condition Error: This sets up the results that are returned if an error occurs while 
evaluating the condition (for example, the LDAP server goes down). This rule is set up to grant 
the user the role of Manager if the condition evaluates to True. If an error occurs, you do not 
want random users assigned the role of Manager. Therefore, for this rule, you need to select 
False. 


7 In the Actions section, click Activate Role. 
8 In the Activate Role box, type Manager, then click OK twice. 
9 On the Policies page, click Apply Changes. 

10 Click Close, select the Manager role, then click Enable. 

11 Click OK, then update Identity Server. 


Creating a Rule for a Contract with ORed Credentials 


A contract with ORed credentials allows the user to decide which credentials to use for 
authenticating. If you are creating a role policy that grants the user the role regardless of which 
method was used for authentication, you can use such a contract just as you would any other 
contract in a condition. However, if you want to base the condition on the user using the contract with 
multiple credentials for authentication and on the user authenticating with a particular credential 
(password, token, or certificate), you need to create a rule with two conditions: one condition checks 
for the contract and the second condition checks for the authenticating credential. 


If the contract with ORed credentials was named OringContracts, the first condition in the rule must 
look similar to the following: 


Figure 8-10 Checking for the Contract 


Condition Group 1 ‘axl 


New w 


if | Authentication Contract: [Current] E feed 


Comparison: String: Equals Y 


Mode: Case Sensitive w 
Value: Authentication Contract w OringContracts w 


Result on Condition Error: Fale w 


This condition verifies that the user used the OringContracts contract for authentication. The second 
condition needs to verify the type of credential that was used. To do this, you need to check for the 
existence of the credential in the Credential Profile. This condition must look similar to the following if 
you are verifying that the user used a certificate for the credential. 
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Figure 8-11 Checking for the Credential 


‘and lf ~| Credential Profile: X509 Public Certificate [GJ Exe 
Comparison: String : Equals w 
Mode: Case Sensitive w 
Value: Credential Profile w x509 Public Certificate w 


Result on Condition Error: Fake w 


The policy engine evaluates the above condition to true when the Credential Profile contains a value 
for the certificate. If the user used another method for authentication, the certificate field is empty, and 
the policy engine evaluates two null entries to false. 


This type of condition works for the LDAP credentials and the X.509 credentials. It does not work for 
the Radius token, because the Credential Profile does not store the Radius token. You need to use “If 
Not” logic to verify that the user authenticated with a token. For example, if the OringContracts 
contract ORed the Radius token class with the Name/Password class, you would know that the user 
authenticated with a token when the password credential has no value. This type of condition must 
look similar to the following: 


Figure 8-12 Using “If Not” Logic 


[And If Not ¥| Credential Profile: LDAP Password» E axes 
Comparison: String: Equals w 
Mode: Case Sensitive w 
Value: Credential Profile Y LDAP Password w 


Result on Condition Error: Fase w 


If the Credential Profile contains a value for the password, this condition evaluates to false because of 
the “And If Not” logic. If the password value in the Credential Profile is empty, this condition evaluates 
to true, and you know that the user authenticated with a Radius token. 


Creating Access Manager Roles in an Existing Role-Based 
Policy System 


If you have already implemented a role-based administration policy for granting access to print, file, 
and LDAP resources, you can leverage your role definitions and use Access Manager policies to 
control access to Web resources. If your role definitions use the following types of LDAP features, 
you can create Access Manager Role policies that use them: 

¢ Values found in LDAP attributes 

¢ Location of the user objects in the directory tree 

+ Membership in groups or roles 
The Access Manager Role policies that you create for these features can then be used to control 
access to protected Web resources. You can manually assign the roles by creating role policies with 
conditions or you can activate roles based on the values in the external source. 

¢ Section 8.2.5.1, “Activating Roles from External Sources,” on page 749 


¢ Section 8.2.5.2, “Using Conditions to Assign Roles,” on page 750 


748 ~~ Access Manager Policies 


8.2.5.1 


Activating Roles from External Sources 


If you have an LDAP attribute, an LDAP group, an LDAP OU, or a Liberty attribute that you are 
currently using for role assignments, you can have Access Manager read its value and activate roles 
based on the values. This allows you to use the same roles for Access Manager access as you are 
using in other parts of your deployment. 


When you create this type of Role policy, you do not need to specify any conditions. The policy 
engine reads the attribute you specify, then assigns roles to users based on the value or values in the 
attribute. If the user has no value for the attribute, the user is assigned no roles. If the user has a 
value for the attribute, the user is assigned a role for each value in the attribute. 

1 In Administration Console Dashboard, click Policies > Policies. 

2 Select the policy container, then click New to create a new policy. 

3 Specify a name for the Role policy, select Identity Server: Roles for the type, then click OK. 

4 On the Rule page in the Actions section, click New > Activate Selected Role. 

5 For this example, select LDAP Group. 


6 To select the group you want to use for role assignments, click Current > [Identity Server Name] 
> [User Store Name] > [Group Name]. 


The distinguished name of this group is the Role name that is assigned to the user. 
7 Select a Multi-Value Separator that is compatible with a distinguished name. 


A comma, which is the default separator, cannot be used because a comma is used to separate 
the components in a distinguished name. Select any other value, such as #. 


Your policy must look similar to the following: 


Edit Rule: LDAP_Group - Rule 1 


Type: Identity Server; Roles 


Description: Doc group assigned as a role 


Priority: 1 & 


Conditions Condition structure: | AND Conditions, OR groups Y 


Condition Group 1 = 


New v 
No conditions in Rule 1, (Actions will always occur unconditionally, ) 


Actions 
New v 


Do Activate Selected Role DAS 
LDAP Group v :  idp-45:Internal:cn=Doc,o=novell w 


Multi-Value Separator: DN Format: LDAP (ex, cn=jsmith,ou=Sales,o=Novell) v 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancet | 


8 Click OK twice, then click Apply Changes. 


9 To enable the role so that it can be used in Authorization and Identity Injection policies, click 
Devices > Identity Servers > Edit > Roles. 


10 Select the check box next to the name of the role, then click Enable. 
11 Click OK. 

12 Update Identity Server. 

13 (Optional) Verify the name used for the role and the user assigned to it: 


13a Enable logging by clicking Devices > Identity Servers > Edit > Logging, then set the 
following values: 
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13b 
13c 
13d 
13e 


13 


> 


File Logging: Select Enabled. 

Echo To Console: Select this option to enable it. 

Application: In the Component File Logger Levels section, set to info. 

Click OK, then update Identity Server. 

Log in to Identity Server by using the credentials of a user who belongs the LDAP group. 
View the log file for Identity Server by clicking Auditing > General Logging 


Select the file (for Windows, select the stdout . log file; for Linux, select the catalina.out 
file), then click Download. 


Look for two log entries (<amLogEntry>) similar to the following: 


<amLogEntry> 2009-10-09T21:58:55Z INFO NIDS Application: AM#500199050: 
AMDEVICEID#CA50FD51DB1EEE3E: AMAUTHID#213E610199A14CEAF27395A6B35F3162: 
IDP RolesPep.evaluate(), policy trace: 
~~RL~1~~~~Rule Count: 1~~Success(67) 
~~RU~RuleID_1223587171711~LDAP_Group~DNF~~@:1~~Success (67) 
~~PA~ActionID_1223588319336~~AddSelectedRoles~cn=Doc~~~Success (0) 
~~PA~ActionID_1223588319336~~AddSelectedRoles~o=novell~~~Success(0) 
~~PC~ActionID_1223588319336~~Document=(ou=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, ou=PartitionsContainer, 
ou=VCDN_Root, ou=accessManagerContainer, o=novell: romaContentCollection 
XMLDoc), Policy=(LDAP_Group), Rule=(1: :RuleID_1223587171711), Action= 
(AddSelectedRole: :ActionID_1223588319336 )~~~~Success(0) 
</amLogEntry> 


<amLogEntry> 2009-10-09T21:58:55Z INFO NIDS Application: AM#500105013: 
AMDEVICEID#CA50FD51DB1EEE3E: AMAUTHID#213E610199A14CEAF27395A6B35F3162: 
Authenticated user cn=jwilson,o=novell in User Store Internal with roles 
"cn=Doc, o=novell", "authenticated". 

</amLogEntry> 


The first <amLogEntry> entry indicates that the action in the LDAP_Group policy was 
successfully assigned. 


The second entry gives the DN of the user and lists the roles assigned to the user: 
cn=Doc,o=novell and authenticated. 


You can now use the cn=Doc,o=novell role when creating Authorization and Identity Injection policies, 
which control access to protected Web resources. Roles activated this way do not appear in the list of 
available roles. You need to use the Data Entry Field to manually type in the role name. For more 
information, see the following: 

+ Chapter 8.3, “Authorization Policies,” on page 760 


¢ Chapter 8.4, “Identity Injection Policies,” on page 810 


Using Conditions to Assign Roles 


e “Creating a Role by Using an LDAP Attribute” on page 751 
e “Creating a Role by Using the Location of the User Objects” on page 752 
e “Creating a Role by Using a Group Membership Attribute” on page 755 
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Creating a Role by Using an LDAP Attribute 


You can assign a user to a role by using a value found in any LDAP attribute in your directory. The 
following example uses the objectClass attribute because every object in an LDAP directory has an 
objectClass attribute that contains the object classes to which the object belongs. This attribute 
contains the name of the object class that was used to create the object as well as the names of the 
superior object classes of this class. All you need to know is the name of the object class you used to 
create your users in the LDAP directory. For example, the following instructions create a Role policy 
for users who were created with the User object class. 


1 In Administration Console Dashboard, click Policies > Policies. 

2 Select the policy container, then click New. 

3 Specify a name for the Role policy, select Identity Server: Roles for the type, then click OK. 
4 In Condition Group 1, click New, then select LDAP Attribute. 

5 In Condition Group 1, select the conditions the user must meet: 


LDAP Attribute: Select the objectClass attribute. If you have not added this attribute, it won't 
appear in the list. Scroll to the bottom of the list, click New LDAP Attribute, specify objectClass 
for the name, then click OK. 


If you are using eDirectory™ for your LDAP directory, you need to specify standard LDAP names 
for the attributes. Access Manager does not support spaces or colons in attribute names. 


Comparison: Select how you want the attribute values to be compared. For the objectClass 
attribute, select String > Contains Substring. 


The objectClass attribute is a multi-valued attribute and, for most objects, contains multiple 
values. For example in eDirectory, users created with the User object class have User, 
organizationalPerson, person, ndsLoginProperties, and top as values in the objectClass 
attribute. 


Mode: Select Case Insensitive. 
Value: Select Data Entry Field and specify User as the value. 


Result on Condition Error: This sets up the results that are returned if an error occurs while 
evaluating the condition (for example, the LDAP server goes down). This rule is set up to grant 
the user the role of UserClass if the condition evaluates to True. If an error occurs, you do not 
want random users assigned the role of UserClass. Therefore, for this rule, you need to select 
False. 


6 In the Actions section, click Activate Role. 
7 Inthe Activate Role box, type UserClass, then click OK. 


The name you specify in the box is the role you want assigned to the users who match the 
condition. 


Your rule must look similar to the following: 
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Type: Identity Server: Roles 
Description: (Object class rule for the UserClass role 


Priority: 1 ~ 


Conditions Condition structure: | AND Conditions, OR groups Y 


Condition Group 1 
New v 


If ¥| LDAP Attribute: objectClass w 


Comparison: String : Contains Substring Y 
Mode: Case Insensitive w 
Value: Data Entry Field w : User 
Result on Condition Error: False w 


Append New Group 


Actions 


Activate Role 
Do Activate Role 


: |UserClass 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


8 Click OK twice, then click Apply Changes. 


9 To enable the role so that it can be used in Authorization and Identity Injection policies, click 
Identity Servers > Edit > Roles. 


10 Select the check box next to the name of the role, then click Enable. 
11 Click OK. 
12 Update Identity Server. 


You can now use this role when creating Authorization and Identity Injection policies, which control 
access to protected Web resources. For more information, see the following: 


¢ Chapter 8.3, “Authorization Policies,” on page 760 
¢ Chapter 8.4, “Identity Injection Policies,” on page 810 
Creating a Role by Using the Location of the User Objects 
If you have created your users in specific containers in your LDAP tree, you can use these container 


objects to assign users to roles. For example, suppose your LDAP tree looks similar to the following 
tree. 
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Figure 8-13 Using an eDirectory Tree for Access Control 


a 


| 


eDirectory Tree 


o=Novell 


Users Users Users 


Such a tree organization can be used to control access to resources. The following instructions 
explain how to create a Role policy for the users created under the Sales container. 


1 In Administration Console Dashboard, click Policies > Policies. 


2 Select the policy container, then click New. 


3 Specify a name for the Role policy, select Identity Server: Roles for the type, then click OK. 


4 In Condition Group 1, click New, and select LDAP OU > [Identity Server Configuration] > [User 


Store] > [DN of the OU]. 
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The following example illustrates how to make these selections: 


Edit Rule: Sales_Role - Rule 1 [2] 


Type: Identity Server: Roles 


Description: |Sales container role policy 


Priority: 
Conditions Condition structure: 


El Condition Group 1 


LDAP OU: [Current] v 
Select LDAP OU 


[Current] 


idp-58.amlab.net > 


idp-58.amlab.net 


Installed User Store > 


Installed User Store |X] 


ou=Dev,o=novell 
ou=HR,o=novell 


ou=Sales,o=novell 


idp-58. amlab.net: Installed User Store:ou=Sales,o=novell 


Comparison: Select how you want the attribute values to be compared. For LDAP OU, select 
Contains. 


Mode: Select One Level if all your users are created in ou=Sales. Select Subtree if your users 
are created in various containers under the ou=Sales container. 


Value: Select LDAP OU, then select [Current]. 


The DN of the authenticated user is compared with the value specified in LDAP OU. If the DN of 
the user contains the LDAP OU value, the user matches the condition. For example, if the DN of 
the user is cn=bsmith,ou=sales,o=novell and the LDAP OU value is ou=sales,o=novell, the user 
matches the condition. If you selected Subtree for the Mode, a user with the following DN also 
matches the condition: cn=djones,ou=provo,ou=sales,o=novell. 


Result on Condition Error: This sets up the results that are returned if an error occurs while 
evaluating the condition (for example, the LDAP server goes down). This rule is set up to grant 
the user the role of Sales if the condition evaluates to True. If an error occurs, you do not want 
random users assigned the role of Sales. Therefore, for this rule, you need to select False. 


5 In the Actions section, click Activate Role. 
6 In the Activate Role box, type Sales, then click OK. 


The name you specify in the box is the role you want assigned to the users who match the 
condition. 
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Your rule must look similar to the following: 


Type: Identity Server: Roles 


Description: (Sales container role policy| 


Priority: 1 & 


Conditions Condition structure; | AND Conditions, OR groups Vv 


Condition Group 1 


New v 


[4] | If vi LDAP OU: ou=Sales,o=novell w 


Comparison: LDAP OU: Contains w 
Mode: One Level w 
Value: LDAP OUw [Current] Y 
Result on Condition Error: False w 


Append New Group 


Actions 


Activate Role 
Do Activate Role 


: [Sales 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


7 Click OK twice, then click Apply Changes. 


8 To enable the role so that it can be used in Authorization and Identity Injection policies, click 
Devices > Identity Servers > Edit > Roles. 


9 Select the check box next to the name of the role, then click Enable. 
10 Click OK. 
11 Update Identity Server. 
You can now use this role when creating Authorization and Identity Injection policies, which control 
access to protected Web resources. For more information, see the following: 
+ Chapter 8.3, “Authorization Policies,” on page 760 
¢ Chapter 8.4, “Identity Injection Policies,” on page 810 


Creating a Role by Using a Group Membership Attribute 


If you have created an LDAP group and assigned users to the group, you can use group membership 
to assign a role to the user. For example, you might have created a first-level managers group and 
made all your first-level managers members of this group. You can then have other groups for your 
upper-level managers. You can create a Role policy that assigns the user a role if the user is a 
member of a specific group. The Role policy can then be used in an Authorization or Identity Injection 
policy to protect a Web resource. 

1 In Administration Console Dashboard, click Policies > Policies. 

2 Select the policy container, then click New. 

3 Specify a name for the Role policy, select Identity Server: Roles for the type, then click OK. 


4 In Condition Group 1, click New, then select LDAP Group. 
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5 In Condition Group 1, select the conditions the user must meet: 


LDAP Group: Select Identity Server Configuration, the user store, then the Group. 
The following figure illustrates this selection process. 


Type: Identity Server: Roles 


Description: Manager role for members of the Sales Managers group 


Priority: 
Conditions Condition structure: 


Condition Group 1 


LDAP Group: [Current] v 


Comparison Select LDAP Group 
Valug 


Result on Condition Erroi 


[Current] 


idp-58.amlab.net > 


idp-58.amlab.net 


Actions Installed User Store > 


New ¥ Installed User Store || 
No Actions in Rule 1 


cn=Managers, ou=Dev,o=novell 


thanges made on this panel must be applied cn=Managers, ou=Sales,o=novell 


OK | Cancel | cn=doc_group,ou=HR,o=novell idp-58.amlab.net:Installed User 


Store:cn=Managers,ou=Sales,o=novell 


Comparison: Select how you want the attribute values to be compared. For LDAP Group, select 
Is Member of. 


Value: Select LDAP Group, then select [Current]. 


The DN of the authenticated user is compared with the members of the LDAP Group. If the DN 
of the user matches one of the members, the user matches the condition. 


Result on Condition Error: This sets up the results that are returned if an error occurs while 
evaluating the condition (for example, the LDAP server goes down). This rule is set up to grant 
the user the role of ManagersGroup if the condition evaluates to True. If an error occurs, you do 
not want random users assigned the role of ManagersGroup. Therefore, for this rule, you need 
to select False. 


6 In the Actions section, click Activate Role. 
7 Inthe Activate Role box, type ManagersGroup, then click OK. 


The name you enter in the box is the role you want assigned to the users who match the 
condition. 
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Your rule must look similar to the following: 


Type: Identity Server: Roles 


Description: Manager role for members of the Sales Managers group 


Priority: 1 & 


Conditions Condition structure: | AND Conditions, OR groups 


ki 


E Condition Group 1 


LDAP Group: cn=Managers,ou=5ales,o=novell Y 


Comparison: LDAP Group: Is Member of w 
Value: LDAP Group Y [Current] v 
Result on Condition Error: False w 


Append New Group 


Actions 


Activate Role 
Do Activate Role 


: \WanagersGroup 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


8 Click OK twice, then click Apply Changes. 


9 To enable the role so that it can be used in Authorization and Identity Injection policies, click 
Devices > Identity Servers > Servers > Edit > Roles. 


10 Select the check box next to the name of the role, then click Enable. 
11 Click OK. 
12 Update Identity Server. 


You can now use this role when creating Authorization and Identity Injection policies, which control 
access to protected Web resources. For more information, see: 


+ Chapter 8.3, “Authorization Policies,” on page 760 
¢ Chapter 8.4, “Identity Injection Policies,” on page 810 
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8.2.6 


8.2.6.1 


Mapping Roles between Trusted Providers 


Identity Server can send roles in an authentication assertion. You can map these roles that are 
received from trusted providers to your own roles. Figure 8-14 illustrates this process. 


Figure 8-14 Role Mapping 


Access to 
Protected Resource 


Authentication at 


Novell.com 
Attribute Set: All Roles Rule Conditions 
v N_Employee DigitalAirlines.com 1 If Roles from Ey 
IDP Service Provider Identity Provider: novell.com 
Liberty | String: Equals 
Role Value: N_EmployeeRole 
a Mapping - 
g Actions: Activate Role: novell_user 
IDP 
SAML 2.0 l 
= 2 If Roles from 
W Attribute Set: All Roles Identity Provider: xyz.com 
XYZ_Empl String: Equals 
Authentication Value: XYZ_Empl 
at XYZ.com . ; Policy 
Actions: Activate Role: xyz_user 


In this example, employees authenticate to identity providers novell.com (Liberty) or xyz.com (SAML 
2.0). Each user is assigned to a role, such as N_EmployeeRole or XYZ_Empl. Attribute sets at each 
of the identity providers are configured to exchange the All Roles attribute with the trusted service 
provider, DigitalAirlines.com. DigitalAirlines.com consumes the authentication assertions, then maps 
the incoming roles to local roles. The mapped roles at DigitalAirlines.com can be used as evaluated 
conditions in authorization policies, which can provide access to resources intended for the 
authenticated employees. 


¢ Section 8.2.6.1, “Prerequisites,” on page 758 
¢ Section 8.2.6.2, “Procedure,” on page 759 


Prerequisites 


O Configure trust between trusted providers, using the Liberty or SAML 2.0 protocol. 


You must be familiar with Chapter 5.2.4, “Configuring SAML 2.0,” on page 471 and 
Chapter 5.2.6, “Configuring Liberty,” on page 509. 

O Configure local authentication. 
You must create an external contract at the service provider that matches the contract of the 
identity provider. See Chapter 5.1, “Local Authentication,” on page 359. 

O Create an attribute set and select the local attribute All Roles in the set. This must be done at the 
identity provider and service provider. 


This attribute set is used to pass roles from an identity provider to an external service provider in 
authentication assertions. See Section 3.5.1, “Configuring Attribute Sets,” on page 80. 
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8.2.6.2 Procedure 


The following procedure describes how the service provider configures this type of role policy for 
novell.com, mapping the N_Employee role to an Access Manager role: 


A OO N RP 


In Administration Console Dashboard, click Policies > Policies. 
Click New, then specify a name for the Role policy. 
Select Identity Server: Roles for the type, then click OK. 
Configure the role policy as shown on the following page. 
Edit Rule: Novell_Employees - Rule 1 [?] 
Type: Identity Server: Roles 
Description: i 
Priority: 1 
Conditions Condition structure: | AND Conditions, OR groups Y 


E Condition Group 1 


Roles from Identity Provider; Novell IDP Liberty v 
Comparison: String: Equals ¥ 


Mode: Case Sensitive w 


Value: Data Entry Field œ; (N_Employee 


Result on Condition Error: False w 


Append New Group | 


Actions 


New v 


Do Activate Role 


| novell user] i 


Changes made on this panel must be applied from the Policies Panel. 


ok č | Cancel | 


In the Conditions section, click New > Roles from Identity Provider. 

Select the trusted identity provider in the drop-down menu. 

For Comparison, select String > Equals. 

Select Value > Data Entry Field. 

Type the name of the role used by the trusted identity provider. 

Under the Actions section, click Activate Role. 

Type the name of the role you want to activate at the trusted service provider. 
Click OK. 

On the Policies page, click Apply Changes. 


To enable the role so that it can be used in Authorization and Identity Injection policies, click 
Identity Servers > Servers > Edit > Roles. 


Select the check box next to the name of the role, then click Enable. 
Click OK. 
Update Identity Server. 
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8.3 


Enabling and Disabling Role Policies 


For a role policy to function, you must enable it for Identity Server configuration. 


1 In Administration Console Dashboard, click Devices > Identity Servers > Edit > Roles. 

2 Select the role policy’s check box, then click Enable. 

3 To disable the role policy, select the role policy’s check box, then click Disable. 

4 After enabling or disabling role policies, update Identity Server configuration on the Servers tab. 


Importing and Exporting Role Policies 


You can import and export role policies to run them in other Identity Server configurations. When you 
import a role, ensure that you have enabled any Liberty profile that is referenced in the role policy, to 
correctly display the policy in the interface. However, the policy still evaluates if you have not enabled 
the profile. 


You must also enable roles after importing them to an Identity Server configuration. See 
Section 8.2.7, “Enabling and Disabling Role Policies,” on page 760. Click Devices > Identity Servers 
> Edit > Roles. 


When you export a role policy, the system saves it as a . txt file at the location of your choosing. 
After you import a role policy, you must update Identity Server configuration. 


To export a role policy: 


1 In Administration Console Dashboard, click Policies > Policies. 

2 Select a policy, then click Export. 

3 (Optional) Modify the name suggested for the file. 

4 Click OK. 

5 Using the features of your browser, specify where you want the file to be copied. 
6 Click OK. 


To import a role policy: 
1 In Administration Console Dashboard, click Policies > Policies. 
2 Click Import, then browse to and select the file. 


3 Click OK. 
4 When the policy appears in the list, click Apply Changes. 


Authorization Policies 


Authorization policies are used when you want to protect a resource based on criteria other than 
authentication, and you want Access Manager to enforce Access restrictions. Authorization policies 
are enforced when a user requests data from a resource. 


Access Manager supports Access Gateway Authorization policies for protecting resources of Access 
Gateway. 
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8.3.1.1 


The first step in creating an Authorization policy is determining the criteria for restricting access. The 
second step is translating those criteria into rules and conditions for a policy. This section describes 
the policy elements, but your resource and your security requirements determine which elements to 
use when creating the policy. 

¢ Section 8.3.1, “Designing an Authorization Policy,” on page 761 

¢ Section 8.3.2, “Creating Access Gateway Authorization Policies,” on page 771 

e Section 8.3.3, “Sample Access Gateway Authorization Policies,” on page 773 

¢ Section 8.3.4, “Conditions,” on page 780 

¢ Section 8.3.5, “Importing and Exporting Authorization Policies,” on page 809 


Designing an Authorization Policy 


When you create an Authorization policy, you need to configure one or more rules. Each rule consists 
of two parts: (1) one or more conditions the user must meet and (2) the action to perform when the 
user meets the conditions or does not’ meet the conditions. The action can be to either allow or deny 
access to the resource. This section describes how to use the following elements when creating a 
policy: 

¢ Section 8.3.1.1, “Controlling Access with a Deny Rule and a Negative Condition,” on page 761 

¢ Section 8.3.1.2, “Configuring the Result on Condition Error Option,” on page 762 

¢ Section 8.3.1.3, “Many Rules or Many Conditions,” on page 763 

¢ Section 8.3.1.4, “Using Multiple Conditions,” on page 763 

¢ Section 8.3.1.5, “Controlling Access with Multiple Conditions,” on page 765 

¢ Section 8.3.1.6, “Using Permit Rules with a Deny Rule,” on page 766 

¢ Section 8.3.1.7, “Using Deny Rules with a General Permit Rule,” on page 767 

¢ Section 8.3.1.8, “Public Policies,” on page 769 

¢ Section 8.3.1.9, “General Design Principles,” on page 769 

¢ Section 8.3.1.10, “Using the Refresh Data Option,” on page 769 

¢ Section 8.3.1.11, “Assigning Policies to Resources,” on page 770 


Controlling Access with a Deny Rule and a Negative Condition 


To deny access to the correct set of users, you need to know the characteristics of the users you don’t 
want to access the resource, as well as the characteristics of the users you do want to access the 
resource. 


Some very simple policies can be created by using a Deny action. For example, suppose you have 
an application that you only want managers to access. If you have set up a role that assigns all 
managers to the Manager role, you can use this characteristic for an Authorization policy. Such a rule 
would be similar to the following: 
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Figure 8-15 Simple Rule 


Edit Rule: Deny_Non-Managers - Rule 1 


Type: Access Gateway: Authorization 


Description: |Deny everyone but managers 


Priority: 1 B 


Conditions Condition structure: | AND Conditions, OR groups ¥ | 


Condition Group 1 


New wv 


fNot ¥| Roles: [Current] ¥ 


Comparison: String: Equals v 


Mode: Case Sensitive w 


Value: Roles w Manager w 


Result on Condition Error: 


Append New Group | 


Actions 


Changes made on this panel must be applied from the Policies Panel, 


ok | Cancel | 


This rule evaluates the user, and if the user does not belong to the Manager role, the user matches 
the condition. The action for matching the condition is to deny access. The managers, who belong to 
the Manager role, do not match the condition and the Deny action is not applied to them. 


The Result on Condition Error option is set to True. You don’t want an error to cause the policy to 
assume that the user is a manager. If an error occurs, you want the policy to assume that the user is 
not a manager, so he or she matches the condition and the Deny action is applied. 


8.3.1.2 Configuring the Result on Condition Error Option 


The Result on Condition Error option allows you to specify what the condition returns when the 
comparison of the two values returns an error rather than the results of the comparison. Select either 
False or True. You need to analyze the logic of your policy carefully, because if you set up this option 
incorrectly, error conditions can allow access to a resource. Consider the following: 


¢ If your rule is a Permit rule and you do not want the action applied when an error occurs, select 
False for this option. 


¢ If your rule is a Deny rule with an If Not condition and you want the action applied when an error 
occurs, select True. 
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8.3.1.3 


8.3.1.4 


Many Rules or Many Conditions 


You can design your policy to have many rules with a single condition and action, or you can design 
your policy to have fewer rules, with each rule containing many conditions. 


For example, suppose you have a resource that you don’t want users accessing on Monday, 
Wednesday, and Friday between 1:00 a.m. and 2:00 a.m. You could set up three rules, one for each 
day, or you could set up one rule with three conditions. If all the conditions have the same action (for 
example, deny access with the same reason), it is simpler to put them in the same rule. However, if 
you have a customized message to return for each day, you need to put them in separate rules. 


Each rule contains the following: 
¢ Zero or more conditions. A condition specifies how the request data is evaluated for a True or 
False match. Conditions are evaluated in the order in which they are listed. 


+ One or more condition groups. Conditions are placed in condition groups, which gives you the 
flexibility of creating a policy that allows the user to match the conditions in one group but not the 
conditions in the other condition groups. Or you can set up the condition groups to require that 
the user matches at least one condition in each condition group. 


+ An action, which grants access, denies access, or redirects the users. 


Conditions, conditions groups, and the interaction among them allow you to create very simple rules 
(if A, then grant access) to very complex rules (if A, B, and C, but not D and E, then grant access). 


Using Multiple Conditions 


The Condition structure option controls how conditions within a condition group interact with each 
other and how condition groups interact with each other. Select one of the following: 


+ AND Conditions, OR groups: If the conditions are ANDed, the user must meet all the 
conditions in a condition group to match the profile. If the condition groups are ORed, the user 
must meet all of the conditions of one group to match the profile. This option allows you to set up 
two or more profiles into which a user could fit and be considered a match. For example, 
suppose you create the following Permit rule: 

The first condition group contains the following conditions: 
1. The user’s department must be Engineering. 


2. The request must come on a weekday. 


The second condition group contains the following conditions: 
1. The user’s department must be Information Services and Technology (IS&T). 
2. The request must come on a weekend. 
With this rule, the engineers who match the first condition group have access to the resource 


during the week, and the IS&T users who match the second condition group have access to the 
resource on the weekend. 


+ OR Conditions, AND groups: If the conditions are ORed, the user must meet at least one 
condition in the condition group to match the profile. If the conditions groups are ANDed, the 
user must meet at least one condition in each condition group to match the profile. For example, 
suppose you create the following allow rule: 


The first condition group contains the following conditions: 
1. The user’s department is Engineering. 
2. The user’s department is Sales. 
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The second condition group contains the following conditions: 
1. The user has been assigned the Party Planning role. 
2. The user has been assigned the Vice President role. 


With this rule, the Vice Presidents of both the Engineering and Sales departments can access 
the resource, and the users from the Engineering and Sales department who have been 
assigned to the Party Planning role can access the resource. 


At the top of each condition group, there is an option that allows you to control whether the user must 
match the conditions to match the profile or whether the user matches the profile if the user does not’ 
match any of the conditions. Depending upon your selection for the Condition structure, you can 
select from the following: 

+ If/lf Not 

+ Or/Or Not 

+ And/And Not 


Conditions also have similar Not options, so that a user can match a condition by not matching the 
specified value. 


Adding Multiple Conditions 


To add another condition to a condition group, click New, then select a condition. To copy an existing 
condition, click the Copy Condition icon (l. New conditions are always added to the end of the 
condition group. Use the Move = buttons to order the conditions in the condition group. 


Adding New Condition Groups 


To add another condition group to the rule, click Append New Group. To copy the existing condition 
group, click the Copy Group icon '&. New condition groups are always added to the end to the 
Conditions section. Use the Move = buttons to order the condition groups. 


Disabling or Moving Conditions and Condition Groups 


Condition groups and conditions within them can be disabled by clicking the Enabled check mark [¥], 
which changes the icon to the Disabled icon |Ð. 


You usually disable a condition or condition group when testing a new rule, and if you decide that the 
condition or condition group is not needed, you can then use the Delete [X] button to delete the 
condition or condition group from the rule. Use the Move F} buttons next to the Delete button to move 
a condition up or down within its group. Condition groups also have Move buttons. 
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8.3.1.5 Controlling Access with Multiple Conditions 


A policy requires multiple conditions when you have more than one required condition for granting 
access. For example, suppose you can easily identity your managers because they have all been 
assigned the role of Manager, and you have a resource that only the sales managers must access. 
Such a policy requires two conditions for granting access: the Manager role and membership in the 
sales department. For a Deny rule, the rule needs two condition groups: 


¢ The first condition group matches all users who are not managers. This causes the Deny action 
to be applied. 


+ The second condition group matches the users who are managers but don’t belong to the sales 
department. Because they match both conditions, the Deny action is applied. For these two 
condition groups to work with this logic, the Condition structure is set to AND Conditions, OR 
groups. 


The users who are managers and who belong to the sales department do not match either condition 
group. The Deny action is not applied, and they are allowed access. 


Such a rule would look similar to the following: 


Figure 8-16 A Rule with Two Condition Groups 


Conditions Condition structure; | AND Conditions, OR groups x] 


El Condition Group 1 
New v 


[if Not ¥| Roles: [Current] v o 


Comparison: String: Equals Y 


Mode: Case Sensitive Y 
Value: Roles w Manager w 


Result on Condition Error: True w 


Fl Condition Group 2 


New wv 
| If v| Roles: [Current] ¥ o 
Comparison: String: Equals Y 


Mode: Case Sensitive w 
Value: Roles w Aanager v 


Result on Condition Error: True w 


And If Not | Liberty User Profile: Department ¥ 


Comparison: String : Equals Y 
Mode: Case Sensitive w 


Value: Data Entry Field ¥ : [sales 
Result on Condition Error: True w 
Append New Group 
Actions 


Display Default Deny Page w 


This second condition group could be implemented as the second rule of the policy. If so, it must be 
set as a lower priority than the first rule. Because most systems would have more users than 
managers, the user rule would be used more frequently, so it must come first. 
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8.3.1.6 Using Permit Rules with a Deny Rule 


You can also create policies that contain one or more Permit rules and then create the lowest priority 
rule in the policy as a Deny rule with no conditions. In such a policy, as soon as an allow match is 
processed, the rest of the rules are not processed and the user is granted access to the resource. 
The Deny rule is only processed if the user does not match one of the allow rules, and because all 
users match a rule with no conditions, the user is denied access to the resource. 


The first rule in such a policy for the sales application would look similar to the following. 
Figure 8-17 Rule 1 Granting Access 


Type: Access Gateway: Authorization 


Description: ‘Sales department permit rule 


Priority: | 1 & | 


Conditions Condition structure: | AND Conditions, OR groups Y“ 


E Condition Group 1 


New ¥ 


E] If ~| Roles: [Current] v E 


Comparison: String : Equals ¥ 
Mode: Case Sensitive ¥ 
Value: Roles ¥ Manager ¥ 


Result on Condition Error: False w 


[¥] | And If v| Liberty User Profile: Department Name ¥ 


Comparison: String : Equals ¥ 
Mode: Case Insensitive Y 
Value: Data Entry Field'¥ : [Sales 


Result on Condition Error: False w 


Append New Group 


Actions 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


The conditions in Rule 1 are ANDed, which requires the user to match both conditions before they are 
granted access to the resource. The priority is set to 1, so this rule is the first rule that Access 
Gateway processes. 
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The second rule would look similar to the following: 


Figure 8-18 Rule 2 Denying Access 


Type: Access Gateway: Authorization 


Description: | 


Priority: 4 ¥ 


Conditions Condition structure: | AND Conditions, OR groups ¥ 


Condition Group 1 = 


New ¥ 
No conditions in Rule 2. (Actions will always occur unconditionally.) 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


Because this rule has no conditions, any user who does not match the first rule does match this rule 
and is denied access. The priority of this rule is set lower than the Permit rule so that the Permit rule 
is processed first. 


Using Deny Rules with a General Permit Rule 


You can also create policies that contain one or more Deny rules and then create the lowest priority 
rule in the policy as a Permit rule with no conditions. In such a policy, as soon as a Deny rule matches 
a user, the rest of the rules are not processed and the user is denied access to the resource. The 
Permit rule is only processed if the user does not match one of the Deny rules. Because all users 
match a rule with no conditions, the user is allowed access to the resource. 


The key to creating this type of policy is making sure all the Deny rules match the users you do not 
want accessing the resource and making sure that the Result on Error Condition option is set 
correctly. 


For example, suppose one of the Deny rules uses an LDAP attribute for the condition and that the 
attribute is a hatSize attribute. Some of your users do not have a hatSize attribute, so when they 
access the resource, the comparison generates an error. If Result on Error Condition option is set to 
False, the action (Deny) is not applied, and the next rule in the policy is processed. If that rule is the 
general Permit rule, then they are allowed access to the resource because they experienced an error. 
To prevent this behavior, you need to set the Result on Error Condition option to True, so that the 
Deny action is applied. Your rule then denies access to everyone whose hatSize attribute matches 
the specified value and everyone who does not have the attribute. 
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The Deny rule for such a policy would look similar to the following: 
Figure 8-19 Deny Rule Configured for Error Conditions 


Type: J2EE Agent: Web Authorization 


Description: [Deny users with a hat size of 10 


Priority: E) 


Conditions Condition structure: | AND Conditions, OR groups | 


Condition Group 1 


lif M LDAP Attribute: hatsize ~ E] Refresh Data Every: Session ¥ 


Comparison: Integer : Equals ¥ 
Value: Data Entry Field w 


Result on Condition Error: True w 


Append New Group 
Actions 


| Do Deny y | 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


For most people, Deny rules are harder to write than Permit rules. You not only need to carefully 
configure the Result on Condition Error option, you must also carefully consider the consequences 
of the condition not matching a user. When a user does not’ match the condition, the Action is not 
applied and the next rule in the policy is evaluated. For example, suppose the URL condition is set to 
the compare the following value: 


http://sales.provo.novell.com/meetings/? 


If the URL in the request is http: //sales.provo.novell.com/meetings/january, the user does 
not match the condition, because the ? applies only to the files in the meetings directory and not to 
the subdirectories. The Action is not applied, and the next rule or policy is evaluated. Consider the 
following possibilities: 


+ If you want the condition to match all files and subdirectories, you need to change the ? wildcard 
to the wildcard. 


¢ If you want the condition to allow access to the files in the /meetings directory but deny access 
to the subdirectories, you need to negate the condition so it evaluates as follows: if the URL is 
not a request for the /meetings/? directory, deny access. If you select this type of condition, you 
need to set the Result on Condition Error option to True. If the comparison returns an error and 
there is the possibility that the request is for a subdirectory, you want the user to be denied 
access. 
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The general Permit rule for a Deny policy would look similar to the following: 


Figure 8-20 General Permit Rule 


Type: J2EE Agent: Web Authorization 


Description: 


Priority: 10 ¥ 


Conditions Condition structure: AND Conditions, OR groups v | 


Condition Group 1 


New ¥ 
No conditions in Rule 2. (Actions will always occur unconditionally. ) 


Actions 


| Do Permit ¥ | 


Changes made on this panel must be applied from the Policies Panel. 


ok | Cancel | 


8.3.1.8 Public Policies 


You can create public authorization policies, which are policies that apply to everyone, by leaving the 
Condition section empty. In the Action section, you specify either to deny or to permit access to the 
resource. Then you assign the policy to the protected resource. 


8.3.1.9 General Design Principles 
When you design a policy, remember the following principles: 


+ Logged-in users are allowed access to a protected resource unless the policy denies access. 
¢ Priority determines the order in which rules are applied. 


+ The Conditions section of the rule must evaluate to True for the Action section to be applied. If 
the Condition section evaluates to False, the Action section is ignored and the policy moves to 
the next rule. If another rule does not exist, the user is granted access to the resource. 


+ Rules are only processed until a user matches the conditions in a rule and its action is applied. If 
a user matches the first rule in a policy, that action is applied, and the rest of the rules in the 
policy are ignored. 


+ 


If two rules have the same priority, Deny rules are applied before Permit rules. 


+ 


After you have designed your policy, created it, and assigned it to a resource, you need to test 
the policy. You need to log in as the type of user who must be granted access, as the type of user 
who must not be granted access, and as a user who generates an error on condition evaluation. 


8.3.1.10 Using the Refresh Data Option 


Authorization policies are processed when a user requests access to a resource. The results and the 
values of the data items are cached for the user session. This means that when the user requests a 
second time to access the resource, the policy is evaluated, but the data values from the first 
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evaluation are used. When a data item is cached for the user session, the user must log out and log 
back in to trigger new data values. (For information about how long the data items are cached, see 
Section 30.6.3, “The Policy Is Using Old User Data,” on page 1230.) 


The LDAP Attribute can be configured to refresh its value according to a specified interval. This 
means the attribute value is read not just on the first request that triggers the policy evaluation, but 
when the interval expires. You can select to cache the value for the user session, the current request, 
or a time interval varying from 5 seconds to 60 minutes. 


If the requested page contains links, you must usually cache the data for more than a single request. 
Each link on the page generates a new request. 


You can use this feature for situations when you do not want to force the user to log in again to gain 
rights to resources or to revoke rights to resources. For example, suppose that you have an 
Authorization policy that grants access based on an LDAP attribute having a “yes” value. Users with a 
“no” value in this attribute are denied access. 


If you don’t enable the Refresh Data option on this attribute in the policy condition, the policy is 
evaluated when the user first tries to access the resource. The value for the attribute is cached for the 
user session, and until the user logs out, that is the value that is used. 


However, if you enable the Refresh Data option on this attribute in the policy condition, the policy is 
evaluated when the user first tries to access the resource. When the user sends a second request to 
access the resource and the cached value has been marked old, the Refresh Data option causes the 
value of the attribute to be read again from the LDAP server. This new value is used to evaluate the 
policy and any other policy that is triggered by the request. 


+ Ifthe value from the first request to the second request changes from no to yes, the user gets 
access to the resource. 
+ Ifthe value from the first request to the second request changes from yes to no, the user is 
denied access to the resource. 
For example: 


+ Ifthe attribute controls access to employee resources and an employee leaves, a quick change 
of this attribute value cuts the employee off from the resources that must be available to 
employees only. 


+ Ifthe attribute controls access to a software download site and a user has just purchased a 
product, a quick change to this attribute value can grant access to the download site. 


IMPORTANT: This feature needs to be used with caution. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are normally cached for the user session. 
Enable this option only on those attributes that are critical to the security of your system or to the 
design of your work flow. 


Assigning Policies to Resources 


For information about how to assign the 
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Creating Access Gateway Authorization Policies 


An Authorization policy specifies conditions that a user must meet to access a resource or to be 
denied access to a resource. Access Gateway enforces these conditions. 


To create an Authorization policy: 


Bh WN PF 


In Administration Console Dashboard, click Policies > Policies. 

Select the policy container, then click New. 

Specify a name for the policy, then select Access Gateway: Authorization for the type of policy. 
Fill in the following fields: 


Description: (Optional) Describe the purpose of this rule. 


Priority: Specify the order in which a rule is applied in the policy, when the policy has multiple 
rules. The highest priority is 1 and the lowest priority is 10. If two rules have the same priority, a 
Deny rule is applied before a Permit rule. 


5 In the Condition Group 1 section, click New, then select one of the following: 


+ 


Authentication Contract: Allows you to control access based on the contract the user 
used for login. For configuration information, see “Authentication Contract Condition” on 
page 781. 


Client IP: Allows you to control access based on the IP address of the client making the 
request. For configuration information, see “Client IP Condition” on page 783. 


Credential Profile: Allows you to control access based on the credentials the user 
specified during authentication. For configuration information, see “Credential Profile 
Condition” on page 785. 


Current Date: Allows you to control access based on the date of the request. For more 
information, see “Current Date Condition” on page 786. 


Day of Week: Allows you to control access based on the day the request is made. For 
configuration information, see Day of Week Condition. 


Current Day of Month: Allows you to control access based on the month the request is 
made. For configuration information, see “Current Day of Month Condition” on page 788. 


Current Time of Day: Allows you to control access based on the time the request was 
made. For configuration information, see “Current Time of Day Condition” on page 789. 


HTTP Request Method: Allows you to control access based on the request method. For 
configuration information, see “HTTP Request Method Condition” on page 790. 


LDAP Attribute: Allows you to control access based on the value of an LDAP attribute. For 
configuration information, see “LDAP Attribute Condition” on page 791. 


LDAP OU: Allows you to control access based on the value of an LDAP organizational unit. 
For configuration information, see “LDAP OU Condition” on page 794. 


Liberty User Profile: Allows you to control access based on the value of a Liberty attribute. 
For configuration information, see “Liberty User Profile Condition” on page 796. 


Roles: Allows you to control access based on the roles a user has been assigned. For 
configuration information, see “Roles Condition” on page 796. 


Risk Score: Allows you to define a condition group as part of the authorization policy that 
uses the risk score from Identity Server to protect a resource. For more information, see 
“Risk Score” on page 798 


URL: Allows you to control access based on the URL in the request. For configuration 
information, see “URL Condition” on page 798. 
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URL Scheme: Allows you to control access based on the scheme in the URL of the request 
(for example, HTTP or HTTPS). For configuration information, see “URL Scheme Condition” 
on page 800. 


URL Host: Allows you to control access based on the hostname in the URL of the request. 
For configuration information, see “URL Host Condition” on page 801. 


URL Path: Allows you to control access based on the path in the URL of the request. For 
configuration information, see “URL Path Condition” on page 802. 


URL File Name: Allows you to control access based on the filename in the URL of the 
request. For configuration information, see “URL File Name Condition” on page 804. 


URL File Extension: Allows you to control access based on the file extension in the URL of 
the request. For configuration information, see “URL File Extension Condition” on page 805. 


Virtual Attribute: Allows you to control access based on the value of the virtual attribute. 
For configuration information, see “Virtual Attribute Condition” on page 806. 


X-Forwarded-For IP: Allows you to control access based on the value in the X-Forwarded- 
For IP header of the HTTP request. For configuration information, see “X-Forwarded-For IP 
Condition” on page 807. 


Condition Extension: (Conditional) If you have loaded and configured an authorization 
condition extension, this option specifies a condition that is evaluated by an outside source. 
This outside source returns either True or False. See the documentation that came with the 
extension for information about what is evaluated. 


Data Extension: (Conditional) If you have loaded and configured an authorization data 
extension, this option specifies the value that the extension retrieves. You can then select to 
compare this value with an LDAP attribute, a Liberty User Profile attribute, a Data Entry 
Field, or another Data Extension. For more information, see the documentation that came 
with the extension. 


6 To add multiple conditions to the same rule, either add a condition to the same condition group or 
create a new condition group. For information about how conditions and condition groups 
interact with each other, see “Using Multiple Conditions” on page 763. 


7 In the Actions section, select one of the following: 
¢ Permit: Allows the user to access the resource. 
¢ Redirect: Specify the URL to which you want users redirected when they meet the 


conditions of this policy. 


Re-authenticate with Contract: Select the action to be performed after execution of the 
rule. If you select Re-authenticate with Contract, select the contract to be used. 


NOTE: If Redirect is configured as an Authorization policy action and you attempt to 
configure Re-authenticate with Contract option instead of Redirect, no contracts are 
displayed. 


To workaround this issue, Select Permit or Deny and then select Re-authenticate with 
Contract. The list of contracts are displayed 


Deny: Select one of the following deny actions: 


Display Default Deny Page: Displays a generic message, indicating that the user has 
insufficient rights to access the resource. 


Deny Message: Allows you to provide a customized message that is displayed to users 
who are denied access. 


Redirect to URL: Allows you to specify a URL that users are redirected to when they are 
denied access. For example: 
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+ Action Extension (Permit): Select an action from the list of permit extensions. This action 
permits access to the resource and performs the additional action that the extension is 
designed to perform. If an action extension is not available, see Section 8.1.6, “Adding 
Policy Extensions,” on page 716 for information about uploading, configuring, and importing 
extensions. 


+ Action Extension (Deny): Select an action from the list of deny extensions. This action 
denies access to the resource and performs the additional action that the extension is 
designed to perform. If a deny extension is not available, see Section 8.1.6, “Adding Policy 
Extensions,” on page 716 for information about uploading, configuring, and importing 
extensions. 


8 (Conditional) If you have installed an action obligation extension, you can click New in the 
Actions section, and select the action. This causes the extension to perform whatever action it is 
designed to perform whenever a user matches the conditions of this rule. This type of action is 
usually always configured in addition to a permit or deny action. If the obligation option is not 
available, see Section 8.1.6, “Adding Policy Extensions,” on page 716 for information about 
uploading, configuring, and importing extensions. 


9 To save the rule, click OK. 
10 To add another rule, click New or to save the policy, click OK, then click Apply Changes. 


11 Assign the policy to a protected resource (see “Assigning an Authorization Policy to a Protected 
Resource” on page 133). 


Sample Access Gateway Authorization Policies 


¢ Section 8.3.3.1, “Sample Policy Based on Organizational Rules,” on page 773 
¢ Section 8.3.3.2, “Sample Workflow Policy,” on page 777 


Sample Policy Based on Organizational Rules 


The following sections describe a scenario with an organizational division, then describe two types of 
policies that enforce the requirements of the scenario: 


+ “Company Scenario” on page 773 
+ “LDAP Context Policies” on page 774 
+ “Role Policies with Authorization Policies” on page 775 


Company Scenario 
Suppose that the company LDAP directory has the following organization: 


ou=sales,o=acme 
ou=dev,o=acme 
ou=hr,o=acme 


Suppose that this company has the following configuration and requirements: 


+ Under each branch of the tree, the system administrator has created the users who work in 
these departments. 


+ Each department has its own Web resources, and other departments must be denied access to 
these resources. 
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With this type of configuration, you can use the LDAP context condition to create authorization 
policies or you can create role policies that are used in conjunction with authorization policies. 


LDAP Context Policies 


With such an organization, you can create a policy that either allows or denies access based on the 
LDAP context of the user’s DN. You can use the LDAP context of the user DN to separate the users 
into their departments and then grant access based on the context match. You need to create 
protected resources for the Web resources of the department, create a policy for each protected 
resource, and assign a policy to the protected resources. 


The following procedure explains how to configure such a policy for the sales department. 
1 Click Policies > Policies > New, specify a name for the policy, select Access Gateway: 
Authorization as the type, then click OK. 
2 For Condition Group 1, click New, then select Credential Profile. 
3 Fill in the following fields: 
LDAP Credentials: Select LDAP User DN. 
Ifflf Not: Select If Not. 
Comparison: Select Contains Substring. 
Mode: Select Case Insensitive. 


Value: Select Data Entry Field. In the text box, type the following value: 
ou=sales, o=acme 


Result on Condition Error: Select True. 


4 Inthe Actions section, select Deny. 
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Your policy must look similar to the following: 


Type: Access Gateway: Authorization 


Description: |LDAP context policy 


Priority: 1 & | 


Conditions Condition structure: | AND Conditions, OR groups ¥ 


E Condition Group 1 


New ¥ 


lif Not m Credential Profile: LDAP User DN ¥ 


Comparison: String : Contains Substring Y 
Mode: Case Insensitive ¥ 


Value: Data EntryFiedy  : ‘oussales,o=acme 


Result on Condition Error: True w 


Changes made on this panel must be applied from the Policies Panel. 


ok | Cancel | 


This sets up the condition so that the following occurs: 
+ When the user does not belong to the sales department, the user is denied access. 
+ When the user belongs to the sales department, the user is granted access. 
+ When an error occurs evaluating the conditions in the rule, the user is denied access. 


5 Assign the policy to the protected Web resources of the sales department (see “Assigning an 
Authorization Policy to a Protected Resource” on page 133). 


6 Repeat these steps for the other two departments, changing the Value field to match the 
appropriate department. 


Role Policies with Authorization Policies 


Because of the company’s organization, you need to create three role policies, one for the sales 
users, one for the development users, and one for the human resource users. You can then use these 
roles as conditions in authorization policies to allow and deny access. The first time you use roles in 
an authorization policy, there is extra setup because you must create the role policies. However, after 
the role policies are created, you can use them in multiple authorization policies. 


The following instructions explain how to use the Sales role to create a policy that controls access to 
a protected resource. For instructions on how to create the Sales role, see “Creating a Role by Using 
the Location of the User Objects” on page 752. 


You need to decide on the type of Authorization policy you want to create. For example, you can 
create a Deny policy that denies access to everyone who does not match the condition (in this case, 
the Sales role). 
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Or you can create a two-rule policy that allows access to everyone that matches the condition. The 
first rule grants access to everyone who has the Sales role, and the second rule denies access to 
everyone who did not match the conditions of the first rule. (Other methods are also possible.) 
Because the proposed Deny policy is very similar to the LDAP Context Policies example, the 
following procedures explain how to create the two-rule policy. 
1 In Administration Console Dashboard, click Policies > Policies > New. 
2 Specify a name for the policy, select Access Gateway: Authorization as the type, then click OK. 
3 (Optional) Provide a description for the rule. 
4 In Condition Group 1, click New, and select Roles. 
5 Fill in the following fields: 
If/If Not: Select If. 
Roles: Select [Current]. 
Comparison: Select String: Equals. 
Mode: Select Case Insensitive 
Value: Select Roles, then select Sales. 
Result on Condition Error: Select False. 
6 Under Actions, select Permit, then click OK. 
These steps create the Permit rule and set up the condition so that the following occurs: 


+ When the user does not match the condition because the user does not belong to the Sales 
role, the policy engine moves to the next rule in the policy. 


+ When the user does match the condition because the user belongs to the Sales role, the 
user is granted access. 


¢ |f an error occurs when evaluating the condition of the policy, the user does not match the 
condition and the policy engine moves to the next rule in the policy. 


7 In the Rule List, click New. 


This second rule is for denying access to everyone who does not match the condition in Rule 1. 
Processing of the policy stops when a user matches a rule; therefore all users who match Rule 1 
are granted access and the policy engine does not evaluate the second rule. 


8 Set the Priority to be 2 or greater. 


You want the Permit rule to be processed first, so it must have a priority of 1. The Deny rule 
needs to be processed last, so it needs a lower priority than the Permit rule. 


9 Leave the Condition Group 1 empty. 


The Conditions section is left empty so that everyone who does not match the conditions of the 
Permit rule is denied access to the resource. 


10 Inthe Actions section, select Deny and either accept the default action or select one of the other 
actions. 


11 Click OK twice. 
12 Click Apply Changes on the Policies page. 


13 Assign the policy to the protected Web resources of the sales department (see “Assigning an 
Authorization Policy to a Protected Resource” on page 133). 
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Sample Workflow Policy 


One of the common workflow problems that an Authorization policy can solve is what to do with users 
who are denied access to resource. Most of the time they have a legitimate reason for trying to 
access the resource and need contact information to request access to the resource. You can add 
this contact information to a Web page and redirect the users to this page when the policy denies the 
user access. 


To create such a workflow, you need to create an HTML page with the necessary information for 
making the request for access. It can be as simple as a contact name or it can be an actual form that 
the user submits to the organization that controls access to the resource. 


You then need to create an Authorization policy that redirects the denied users to this page. The 
following sample policy uses a role for Access condition, but the same workflow can be created using 
any of the other conditions available for an Authorization policy. For this example, assume that the 
user is granted a Master role if the user is a member of the Master group. The organization that 
controls access to the resource is the owner of the Master group and can add and delete members 
from the group. When the owner of the Master group receives a request for access to the resource, 
the owner can evaluate the user, and if the user meets their standards, the owner adds the user to the 
Master group. 


You can use the Master group to create an Access Manager Role policy. This policy for the Master 
role must look similar to the following: 


Figure 8-21 A Role Policy with an LDAP Group Condition 


Type: Identity Server: Roles 


Description: [master role assigned to members of the| Master group 
Priority: | 1 >| 
Conditions Condition structure: | AND Conditions, OR groups ~] 


Condition Group 1 
New v 


| If >| LDAP Group: = cn=M\aster,o=novell w E] 


Comparison: LDAP Group : Is ember of w 
Value: LDAP Group w [Current] ¥ 
Result on Condition Error: False w 


Append New Group 


Actions 


Activate Role 
Do Activate Role 


H [Master 


Changes made on this panel must be applied from the Policies Panel, 


OK l Cancel | 


This rule grants the user the Master role if the user belongs to the cn=Master,o=novell LDAP group. If 
the user does not’ belong to this group or if an error occurs trying to get the data, the user is not 
assigned the role. This occurs because both the condition and the Result on Condition Error 
evaluate to False, which prevents the Action from being applied. 


After creating the Role policy, apply the changes and enable the Role for Identity Server. 
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You can then use this role to create an Authorization policy that contains two rules. The first rule 
grants access to the users who have the Master role (and are therefore members of the Master 
group). This rule must look similar to the following: 


Figure 8-22 A Permit Rule with a Role Condition 


Type: Access Gateway: Authorization 


Description: |Allow access if the user has the Master role. | 


Priority: 1 


Conditions Condition structure: AND Conditions, OR groups “~ | 


| | Condition Group 1 


Roles: [Current] ~ O 


Comparison: String: Equals v 


Mode: Case Sensitive w 
Value: Roles w Aħaster w 


Result on Condition Error: False w 


Append New Group 


Actions 


Changes made on this panel must be applied from the Policies Panel. 


oK | Cancet | 


This rule permits users who are assigned the Master role to have access to the resource. If the user 
does not match the condition or if an error occurs accessing the user’s role information, the user is 
sent to the next rule because both the condition and the Result on Condition Error evaluate to False. 


The second rule in the policy must deny access to those who are not assigned the Master role and 
must redirect them to the page where they can request access. You can do this with a rule that 
checks to see if they are assigned the Master role. In this type of rule, the condition needs to be an If 
Not condition. 
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Figure 8-23 A Deny Rule with a Redirect URL 


Type: Access Gateway: Authorization 


Description: |Deny access if not assigned the Master role. 


Priority: 2 B 


Conditions Condition structure: | AND Conditions, OR groups ~“ 


iv] Condition Group 1 
New v 


E | itNot | Roles: [Current] ¥ 


Comparison: String : Equals © 
Mode: Case Sensitive w 
Value: Roles v Master w 


Result on Condition Error; True w 


Append New Group 


Actions 


Do Redirect ¥ Redirect to URL: 


|http: {divi mycompany. com/webserver/ master. html 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


With an If Not condition, the condition evaluates to True when the user does not match the condition. 
With such a rule, you want the Result on Condition Error to also evaluate to True. If there is an error 
obtaining role information for the user, you don’t want the rule to assume that the user had the Master 
role. You want the rule to assume that the user had no roles, or in other words, you want the error 
condition to evaluate to True. 


Because the condition evaluated to True, the Action is applied to the user. The value specified in the 
Redirect to URL text box must specify the page that contains the information about how to request 
access. 


This redirect rule could be the only rule in the Authorization policy, because the users who are 
assigned to the Master role do not match the rule and are thus allowed access. Having the first rule 
that grants access because they have the Master role just makes the logic of the policy clearer. 


If you create the first rule that grants users with the Master role access, you can use a general Deny 
rule for the second rule. 
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It must look similar to the following: 


Figure 8-24 A General Deny Rule 


Type: Access Gateway: Authorization 


Description: [Redirect all users who do not match Rule 1 
Priority: [2 >| 
Conditions Condition structure: [ann Conditions, OR groups | 


Condition Group 1 = 


New w 
No conditions in Rule 2. (Actions wil! always occur unconditionally. ) 


Actions 


Do Redirect © Redirect to URL: 


[http://www mycompany. com/webserver/ master, html 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel | 


A general Deny rule has no conditions, so it matches everyone that does not match the first rule in the 
policy. You can add more rules to this policy to tighten security so that not all users are redirected to 
the site that contains the information about how to request access. For this type of policy, the last rule 
would be a general Deny rule with no conditions and without a redirect. The rules between Rule 1, 
which granted access to people assigned to the Master role, and the last rule, which denies 
everyone, must be rules that identify the types of users who have legitimate reasons for requesting 
access, and these rules must contain the redirect action. 


After you have saved the Authorization policy, you need to assign it to the protected resource or 
resources that require the Master role, then update Access Gateway. 


Conditions 


This section describes the possible conditions for an Authorization policy. Some conditions can be set 
up so that the current values in the request are compared against static values (A to B), or you can 
compare static values to current values in the request (B to A). Within one policy, you must probably 
decide which direction to set up the comparisons and remain consistent unless there is a compelling 
reason to switch the direction for a particular condition. 


For example, suppose you set up a rule to allow access to a resource only during the weekdays 
(Monday through Friday). You set up four of these conditions to compare if the date when the request 
is made matches with Monday, Tuesday, Wednesday, or Thursday. You set up the fifth condition to 
compare whether Friday matches the date when the request is made. This works, but maintaining this 
policy is more difficult because each new policy manager will look at the Friday condition and wonder 
why it is configured differently. 


Many conditions, when used as the sole condition of a rule, do not make very useful rules. For 
example, you can create a rule that grants access if the user specifies a specific URL in the request. 
Such a rule has limited application. But a rule that requires that the request contain a specific URL 
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and that the user have a specific role has greater application because it can be used to limit access to 
the URL based on the user's role. For information about how conditions can be ANDed or ORed 
together or placed in different condition groups, see “Using Multiple Conditions” on page 763. 


Authorization policies use the following conditions: 


¢ Section 8.3.4.1, “Authentication Contract Condition,” on page 781 
¢ Section 8.3.4.2, “Client IP Condition,” on page 783 

¢ Section 8.3.4.3, “Credential Profile Condition,” on page 785 

¢ Section 8.3.4.4, “Current Date Condition,” on page 786 

¢ Section 8.3.4.5, “Day of Week Condition,” on page 787 

¢ Section 8.3.4.6, “Current Day of Month Condition,” on page 788 
¢ Section 8.3.4.7, “Current Time of Day Condition,” on page 789 
¢ Section 8.3.4.8, “HTTP Request Method Condition,” on page 790 
¢ Section 8.3.4.9, “LDAP Attribute Condition,” on page 791 

¢ Section 8.3.4.10, “LDAP OU Condition,” on page 794 

¢ Section 8.3.4.11, “Liberty User Profile Condition,” on page 796 
¢ Section 8.3.4.12, “Roles Condition,” on page 796 

¢ Section 8.3.4.13, “Risk Score,” on page 798 

¢ Section 8.3.4.14, “OAuth Scopes,” on page 798 

¢ Section 8.3.4.15, “URL Condition,” on page 798 

¢ Section 8.3.4.16, “URL Scheme Condition,” on page 800 

¢ Section 8.3.4.17, “URL Host Condition,” on page 801 

¢ Section 8.3.4.18, “URL Path Condition,” on page 802 

¢ Section 8.3.4.19, “URL File Name Condition,” on page 804 

¢ Section 8.3.4.20, “URL File Extension Condition,” on page 805 
¢ Section 8.3.4.21, “Virtual Attribute Condition,” on page 806 

¢ Section 8.3.4.22, “x-Forwarded-For IP Condition,” on page 807 
¢ Section 8.3.4.23, “Condition Extension,” on page 808 

¢ Section 8.3.4.24, “Data Extension,” on page 808 

¢ Section 8.3.4.25, “Using the URL Dredge Option,” on page 808 
¢ Section 8.3.4.26, “Edit Button,” on page 809 


For the specific policies they can be used in, see Section 8.3.2, “Creating Access Gateway 
Authorization Policies,” on page 771. 


Authentication Contract Condition 


The Authentication Contract condition matches the contract the user logged in with to the contract 
specified in this condition. Identity Server has the following default contracts: 
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Name/Password - Basic basic/name/password/uri 
Name/Password - Form name/password/uri 

Secure Name/Password - Basic secure/basic/name/password/uri 
Secure Name/Password - Form secure/name/password/uri 


To configure other contracts for your system, click Devices > Identity Servers > Edit > Local > 
Contracts. 


To specify an Authentication Contract condition, fill in the following fields: 


Authentication Contract: To compare the contract that the user used with a static value, select 
Current. To compare a static value with what the user used, select a contract from the list. 


If you have created more than one Identity Server configuration, select the configuration that 
corresponds to the configuration your Access Gateway is configured to trust, then select the contract. 
The name of the contract is displayed. When you select this name, the configurations that contain a 
definition for this contract are highlighted. 


If you select a contract that is defined on only one of your configurations, be aware that you must 
change this policy when you change configurations. If you select a contract that is defined in all your 
configurations, this policy requires no modifications and continues to function when you change 
configurations. 


For example, the following policy has selected Name/Password - Basic as the contract: 
Figure 8-25 An Authentication Contract Defined by Multiple Identity Server Configurations 


Condition Group 1 


New w 


[4] | tr 


Comparison: String : EqSelect Authentication Contract [x 
Mode: Case Sens; [Current] 


Value: Authentic! jqp-43,amlab.net > 
Result on Condition Error: False w idp-51.amlab.net > 


Append New Group | 


Two Identity Server configurations have been defined (idp-43.amlab.net and idp-51.amlab.net). Both 
configurations are highlighted because Name/Password - Basic is a contract that is automatically 
defined for all Identity Server configurations. Because it is defined on both configurations, this policy's 
function is the same, regardless of which configuration is selected as the trusted configuration. 


Comparison: Specify how the contract is compared to the data in the Value field. Select either a 
string comparison or a regular expression: 


+ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 
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¢ Starts with: Indicates that the Authentication Contract value must begin with the letters 
specified in the Value field. 


+ Ends with: Indicates that the Authentication Contract value must end with the letters 
specified in the Value field. 


+ Contains Substring: Indicates that the Authentication Contract value must contain the 
letters, in the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the value you want to compare with the Authentication Contract value. If you select a 
static value for the Authentication Contract value, select Authentication Contract and Current. If you 
select Current for the Authentication Contract value, select Authentication Contract, then select the 
name of a contract. 


Other value types are possible if you selected Current for the Authentication Contract value. For 
example: 


+ You can select Data Entry Field. The value specified in the text box must be the URI of the 
contract for the conditions to match. For a list of these values, click Access Manager > Identity 
Servers > Edit > Local > Contracts. 


¢ If you have defined a Liberty User Profile attribute for the URI of authentication contracts, you 
can select Liberty User Profile and your defined attribute. 


+ If you have defined an LDAP attribute for the URI of the authentication contracts, you can select 
LDAP Attribute and your defined attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Client IP Condition 


The Client IP condition allows you to use the IP address of the user making the request to determine 
whether the user is allowed access to a resource. 


NOTE: Client IP will support IPv4 addresses and not IPv6 addresses. 


Fill in the following fields: 
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Comparison: Specify how the client IP address is compared to the data in the Value field. Select 
either an IP comparison or a regular expression: 


+ Comparison: IP: Specifies that you want the values compared as IP addresses. Select one of 


the following: 


+ Equals: Allows you to specify an IP address that the client must match. You can specify 


more than one. 


+ In Range: Allows you to specify a range of IP addresses that the client's address must fall 
within. You can specify more than one range. 


+ In Subnet: Allows you to specify the subnet that the client’s address must belong to. You 
can specify more than one subnet. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. If you select this option, you must also specify a mode. Select one or more 


of the following: 


Canonical Equivalence 


Case Insensitive 
Comments 

Dot All 
Multi-Line 
Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Select Data Entry Field and specify a value appropriate for your comparison type. Use the 
Edit button to access a text box where you can enter multiple values, each on a separate line. (For 
more information, see “Edit Button” on page 809.) Use the Add button to add values one at a time. 


For example: 

Comparison Type Value 

Equals 10.10. 
10.10. 

In Range 10.10. 
10.10. 

In Subnet 10.10. 
10.10. 


10.10.10.100 
10.10.20.100 


22 
22 


Other values types are possible. For example, if your user store contains an LDAP attribute with the 
IP address of your users, you could select to compare the client's current IP address with the stored 
value by using an LDAP attribute or a Liberty User Profile value. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 


error occurs, select True. 
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Credential Profile Condition 


The Credential Profile condition allows you to control access based on the credentials the user 
entered when authenticating to the system. 


To set up the matching for this condition, fill in the following fields: 


Credential Profile: Specify the type of credential your users are using for authentication. If you have 
created a custom contract that uses credentials other than the ones listed below, do not use the 
Credential Profile as a condition. 


To configure the Credential Profile condition, select one of the following: 


+ LDAP Credentials: If you prompt the user for a username, select this option, then select LDAP 
User Name (the cn of the user), LDAP User DN (the fully distinguished name of the user), or 
LDAP Password. 


The default contracts assign the cn attribute to the Credential Profile. If your user store is an 
Active Directory server, the SAMAccountName attribute is used for the username and stored in 
the cn field of the LDAP Credential Profile. 


+ X509 Credentials: If you prompt the user for a certificate, select this option, then select one of 
the following: 


+ X509 Public Certificate Subject: Retrieves the subject field from the certificate, which can 
match the DN of the user, depending upon who issued the certificate. 


+ X509 Public Certificate Issuer: Retrieves the issuer field from the certificate, which is the 
name of the certificate authority (CA) that issued the certificate. 


+ X509 Public Certificate: Retrieves the entire certificate, Base64 encoded. 
+ X509 Serial Number: Retrieves the serial number of the certificate. 
¢ SAML Credential: If your users authenticate using a SAML assertion, select this option. 
Comparison: Select one of the following types: 
¢ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 
¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the Credential Profile value must begin with the letters specified 
in the Value field. 


+ Ends with: Indicates that the Credential Profile value must end with the letters specified in 
the Value field. 


+ Contains Substring: Indicates that the Credential Profile value must contain the letters, in 
the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 
Mode: Select the mode appropriate for the comparison type: 
+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 
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Dot All 
Multi-Line 
Unicode 
Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the second value for the comparison. Select one of the following data types: 
+ LDAP Attribute: If you have an LDAP attribute that corresponds to the Credential Profile you 
have specified, select this option and the attribute. 


¢ Liberty User Profile: If you have a Liberty User Profile attribute that corresponds to the 
Credential Profile you have specified, select this option and the attribute. 


¢ Data Entry Field: Specify the string you want matched. Be aware of the following requirements: 


¢ If you selected LDAP User DN as the credential, you need to specify the DN of the user in 
the Value text box. If the comparison type is set to Contains Substring, you can match a 
group of users by specifying a common object that is part of their DNs, for example 
ou=sales. 


+ If you selected X509 Public Certificate Subject as the credential, you need to specify all 
elements of the Subject Name of the certificate in the Value text box. Separate the elements 
with a comma and a space, for example, o=novell, ou=sales. If the comparison type is set to 
Contains Substring, you can match a group of certificates by specifying a name that is part 
of their Subject Name, for example ou=sales. 


Other values are possible. Your policy requirements determine whether they are useful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Current Date Condition 


The Current Date condition allows you to use the date to determine whether the user is allowed 
access to a resource. 


Fill in the following fields: 


Comparison: Specify how the current date is compared to the data in the Value field. Select one of 
the following types: 


+ Comparison: Date: Specifies that you want the values compared as dates. Select one of the 
following date operators: 
+ Equals: Requires that the current date must equal the specified value. 
+ Greater Than: Requires that the current date be after the specified value. 


+ Greater Than or Equal to: Requires that the current date be after or equal to the specified 
value. 


+ Less Than: Requires that the current date be before the specified value. 


+ Less Than or Equal to: Requires that the current date be before or equal to the specified 
value. 
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+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. Be aware the regular expression matching uses the entire date of the 
server in its matching. Therefore if the value you are matching is 8, the 8 can produce a match 
for the year (2008), the month (8), and the day (8, 18, 28). 


If you select this option, you must also specify a mode. Select one or more of the following: 
Canonical Equivalence 

Case Insensitive 

Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Date Format: If you selected a date comparison, specify the format of the Value field. Select one of 
the following formats: 

+ DIMIY = 1/Jul/2009 or 1/7/2009 
¢ D-M-Y = 1-Jul-2009 or 1-7-2009 
¢ D.M.Y = 1.Jul.2009 or 1.7.2009 
+ MIDIY = Jul/1/2009 or 7/1/2009 
¢ M-D-Y = Jul-1-2009 or 7-1-2009 
¢ M.D.Y = Jul.1.2009 or 7.1.2009 
+ YYYY-MM-DD = 2009-07-01 

+ YYYY.MM.DD = 2009.07.01 


D specifies a number from 1 to 31. M specifies a number from 1 to 12 or the name of the month in 
three letters (Sep) or complete (September). Y specifies the year in a four-digit format. 


Value: Specify the second value for the comparison. If you select Data Entry Field as the value type, 
specify the date in the format you select in the Date Format field. 


Other value types are possible. Your policy requirements determine whether they are useful. If you 
have set up a Liberty User Profile or an LDAP attribute that corresponds to the date, you can use this 
option and select your attribute. The Date Format field does not apply to these value types. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Day of Week Condition 


The Current Day of Week condition allows you to restrict access based on which day of the week the 
request is made. Fill in the following fields: 


Current Day of Week: Select the name of the day from the list. To compare the day specified in the 
current request with a static value, select Current. To compare a static value with the day specified in 
the current request, select the name of a day from the list. 
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Comparison: Specify how the current day of the week is compared to the data in the Value field. 
Select one of the following types: 


+ Comparison: Day of Week: Specifies that you want the values compared as a day of the week. 
Select one of the following operators: 


+ Equals: Allows you to specify a day that the client must match. 


+ In Range: Allows you to specify a range of days that the client’s request must fall within, for 
example, Monday to Friday. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. Be aware that regular expression matching uses the entire date of the 
server in its matching. Therefore if the value you are matching is M, the M can produce a match 
for months (March and May) and for time zones (such as MST). 


If you select this option, you must also specify a mode. Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the second value for the comparison. If you select Current for the Current Day of 
Week field, you need to specify a static value. If you select a static value for the Current Day of the 
Week field, you need to select Current for the Value field. 


If you select Data Entry Field as the value type, days of the week are specified in the following format: 


Sun or Sunday 
Mon or Monday 
Tue or Tuesday 
Wed or Wednesday 
Thu or Thursday 
Fri or Friday 
Sat or Saturday 


If you selected In Range as the comparison type, specify the first day of the range in the left text box 
and the end day of the range in the right text box. 


Other value types are possible. Your policy requirements determine whether they are useful. If you 
have set up a Liberty User Profile or an LDAP attribute that corresponds to a day of the week, you 
can use this option and select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Current Day of Month Condition 


The Current Day of Month condition allows you to restrict access based on the day of the month the 
request is made. Fill in the following fields: 
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Comparison: Specify how the current day of the month is compared to the data in the Value field. 
Select one of the following types: 


+ Comparison: Day of Month: Specifies that you want the values compared as a day of the 
month. Select one of the following operators: 


¢ Equals: Allows you to specify a day that the client must match. 
+ In Range: Allows you to specify a range of days that the client’s request must fall within. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. Regular expression matching uses the entire date of the server in its 
matching. Therefore if the value you are matching is 8, the 8 can produce a match for the year 
(2008), the month (8), and the day (8, 18, 28). If you want to match only on a day of the month 
(1-31), you need to use the Day of Month comparison rather than a Regular Expression 
comparison. 


If you select this option, you must also specify a mode. Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the second value for the comparison: 


¢ If you select Equals for the comparison type, you would normally select Data Entry Field for the 
Value field and specify a number from 1 to 31 in the text box. 


¢ If you select In Range for the comparison type, you would normally select Data Entry Field for 
the Value field and specify the first value of the range in the first text box and the second value of 
the range in the second text box. If you specify 1 in the first box and 15 in the second box, you 
can use this condition to restrict access between the first day of the month and the 15th day. 


Other value types are possible. Your policy requirements determine whether they are useful. If you 
have set up a Liberty User Profile or an LDAP attribute that corresponds to a day of the month, you 
can use this option and select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Current Time of Day Condition 


The Current Time of Day condition allows you to restrict access based on the time the request is 
made. Fill in the following fields: 


Comparison: Specify how the current time of day is compared to the data in the Value field. Select 
one of the following types: 


+ Comparison: Time: Specifies that you want the values compared as time. Select one of the 
following: 


+ Greater Than: Requires that the current time is greater than the specified value. 
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+ Greater Than or Equal to: Requires that the current time is greater than or equal to the 
specified value. 


+ Less Than: Requires that the current time is less than the specified value. 


+ Less Than or Equal to: Requires that the current time is less than or equal to the specified 
value. 


+ In Range: Requires that the current time must fall within the specified range, such as 08:00 
and 17:00. 


If you specify this type of comparison, you must also specify a time zone. Select either the Local 
time zone or GMT (Greenwich Mean Time). 


¢ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. Regular expression matching uses the entire date and time of the server in 
its matching. Therefore if the value you are matching is 8, the 8 can produce a match for the year 
(2008), the month (8), the day (8, 18, 28), the hour (8), the minute (8, 18, 28, 38, 48) and the 
second (8, 18, 28, 38, 48). 


If you select this option, you must also specify a mode. Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the second value for the comparison. If you select Data Entry Field as the value type, 
hours and minutes are specified in the following format: 


hour :minute 
Hour is a number from 00 to 23, and minute is a number from 00 to 59. 


Time can only be specified in a 24-hour clock format. For example, 8 am is 08:00 and 5:30 pm is 
17:30. 


Other value types are possible. Your policy requirements determine whether they are useful. If you 
have set up a Liberty User Profile or an LDAP attribute that corresponds to the time of day, you can 
use this option and select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


HTTP Request Method Condition 


The HTTP Request Method condition allows you to restrict accessed based on the request method in 
the current request. 


HTTP Request Method: Select the request method from the list or select Current to specify the 
method in the current request. 
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Comparison: Specify how the HTTP Request Method is compared to the data in the Value field. 
Select one of the following types: 


+ Comparison: String: Specifies that you want the values compared as strings and how you want 
the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the HTTP Request Method value must begin with the letters 
specified in the Value field. 


+ Ends with: Indicates that the HTTP Request Method value must end with the letters 
specified in the Value field. 


¢ Contains Substring: Indicates that the HTTP Request Method value must contain the 
letters, in the same sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the value you want compared to the HTTP Request Method value. If you selected a 


method from the list for the HTTP Request Method value, select HTTP Request Method > Current. If 
you selected Current for the HTTP Request Method value, select a request method from the list. 


Other value types are possible. Your policy requirements determine whether they are useful. If you 
have set up a Liberty User Profile or an LDAP attribute that corresponds to an HTTP Request 
Method, you can use this option and select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


LDAP Attribute Condition 


The LDAP Attribute condition allows you to restrict access based on a value in an LDAP attribute 
defined for the inetOrgPerson class or any other LDAP attribute you have added. You can have the 
user's attribute value retrieved from your LDAP directory and compared to a value of the following 
type: 

+ Roles from an identity provider 

+ Date and time and its various elements 


+ URL and its various elements 
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+ IP address 

e Authentication contract 

¢ Credential profile 

+ HTTP request method 

¢ Liberty User Profile attribute 

¢ Static value in a data entry field 
This condition is one of the slower conditions to process because the value needs to be retrieved 
from the LDAP server. If the value is not time sensitive, you can have attribute value sent in the 
assertion when the user authenticates. Its value is then in cache and available. For configuration 


information, click Devices > Identity Servers > Servers > Edit > Liberty [or SAML 1.0 or SAML 2.0] > 
[Provider] > Attributes. 


To set up the matching for this condition, fill in the following fields: 


LDAP Attribute: Specify the LDAP attribute you want to use in the comparison. Select from the listed 
LDAP attributes. To add an attribute that isn’t in the list, scroll to the bottom of the list, click New LDAP 
Attribute, then specify the name of the attribute. 


Refresh Data Every: Sends a query to the LDAP server to verify the current value of the attribute 
according to the specified interval. Because querying the LDAP server slows down the processing of 
a policy, LDAP attribute values are normally cached after the value has been obtained. The default 
cache interval is for the user session. You must change the value of this option from Session to a 
more frequent interval only on those attributes that are critical to the security of your system or to the 
design of your work flow. 


You can select to cache the value for the session, for the request, or for a time interval varying from 5 
seconds to 60 minutes. For more information about this option, see “Using the Refresh Data Option” 
on page 769. 


Comparison: Specify how you want the values compared. All data types are available. Select one of 
the following that matches the value type of your attribute: 


+ Date: Specifies that you want the values compared as dates. Select one of the following date 
operators: 
+ Equals: Indicates that the current date must be equal to the specified value. 
+ Greater Than: Indicates that the current date be after the specified value. 


+ Greater Than or Equal to: Indicates that the current date be after or equal to the specified 
value. 


+ Less Than: Indicates that the current date be before the specified value. 


+ Less Than or Equal to: Indicates that the current date be before or equal to the specified 
value. 


+ Day of Week: Specifies that you want the values compared as a day of the week. Select one of 
the following operators: 


¢ Equals: Allows you to specify a day that the specified value must match. 


+ In Range: Allows you to specify a range of days that the specified value must fall within, for 
example, Monday to Friday. 


+ Day of Month: Specifies that you want the values compared as a day of the month. Select one 
of the following operators: 


¢ Equals: Allows you to specify a day that the specified value must match. 
+ In Range: Allows you to specify a range of days that the specified value must fall within. 
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¢ Integer: Specifies that you want the values compared as integers. Select one of the following: 
¢ Equals: Indicates that the integer value must be equal to the specified value. 
+ Greater Than: Indicates that the integer value must be greater than the specified value. 


+ Greater Than or Equal to: Indicates that the integer value must be greater than or equal to 
the specified value. 


¢ Less Than: Indicates that the integer value is less than the specified value. 


+ Less Than or Equal to: Indicates that the integer value is less than or equal to the 
specified value. 


¢ IP: Specifies that you want the values compared as IP addresses. Select one of the following: 


¢ Equals: Allows you to specify an IP address that the specified value must match. You can 
specify more than one. 


+ In Range: Allows you to specify a range of IP addresses that the specified value must fall 
within. You can specify more than one range. 


+ In Subnet: Allows you to specify the subnet that the specified value must belong to. You 
can specify more than one subnet. 


¢ LDAP OU: Contains: Specifies that you want the condition to determine whether the user is 
contained by a specified organizational unit. 


¢ Attribute: Does Exist? Specifies that you want the condition to determine whether the user has 
an LDAP attribute. This is a unary condition. 


¢ Regular Expression: Matches: Specifies that you want the values compared as regular 
expressions. 


¢ String: Specifies that you want the values compared as strings and how you want the string 
values to be compared. Select one of the following: 


+ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the attribute value must begin with the letters specified in the 
Value field. 


+ Ends with: Indicates that the attribute value must end with the letters specified in the Value 
field. 


¢ Contains Substring: Indicates that the attribute value must contain the letters, in the same 
sequence, as specified in the Value field. 


¢ Time: Specifies that you want the values compared as time. Select one of the following: 
+ Greater Than: Indicates that the current time is greater than the specified value. 


+ Greater Than or Equal to: Indicates that the current time is greater than or equal to the 
specified value. 


+ Less Than: Indicates that the current time is less than the specified value. 


+ Less Than or Equal to: Indicates that the current time is less than or equal to the specified 
value. 


+ In Range: Indicates that the current time must fall within the specified range, such as 08:00 
and 17:00. 


¢ URL: Equals: Specifies that you want the values compared as URLs. 


+ URL Scheme: Specifies that you want the values compared as scheme strings and how you 
want the values compared. Select one of the following: 


¢ Equals: Indicates that the URL scheme must contain the same letters, in the same order as 
specified in the value. 
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¢ Starts with: Indicates that the URL scheme must begin with the letters specified in the 
value. 


+ Ends with: Indicates that the URL scheme must end with the letters specified in the value. 


+ Contains Substring: Indicates that the URL scheme must contain the letters, in the same 
sequence, as specified in the value. 


¢ URL Host: Equals: Specifies that you want the values compared as hostnames. 


¢ URL Path: Specifies that you want the values compared as paths and how you want the string 
values compared. Select one of the following: 


¢ Equals: Indicates that the URL path must contain the same letters, in the same order as 
specified in the value. 


¢ Starts with: Indicates that the URL path must begin with the letters specified in the value. 
¢ Ends with: Indicates that the URL path must end with the letters specified in the value. 


+ Contains SUbstring: Indicates that the URL path must contain the letters, in the same 
sequence, as specified in the Value field. 


¢ URL File: Specifies that you want the values compared as filenames and how you want the 
names compared. Select one of the following: 


¢ Equals: Indicates that the filenames must contain the same letters, in the same order as 
specified in the value. 


¢ Starts with: Indicates that the filenames must begin with the letters specified in the value. 
+ Ends with: Indicates that the filenames must end with the letters specified in the value. 


+ Contains Substring: Indicates that the filenames must contain the letters, in the same 
sequence, as specified in the Value field. 


¢ URL File Extension: Specifies that you want the values compared as file extensions and how 
you want the file extensions compared. Select one of the following: 


+ Equals: Indicates that the file extensions must contain the same letters, in the same order 
as specified in the value. 


¢ Starts with: Indicates that the file extensions must begin with the letters specified in the 
value. 


+ Ends with: Indicates that the file extensions must end with the letters specified in the value. 


¢ Contains Substring: Indicates that the file extensions must contain the letters, in the same 
sequence, as specified in the Value field. 


Mode: Select the mode, if available, that matches the comparison type. For example, if you select to 
compare the values as strings, you can select either a Case Sensitive mode or a Case Insensitive 
mode. 


Value: Specify the second value for the comparison. All data types are available. For example, you 
can select to compare the value of one LDAP attribute to the value of another LDAP attribute. Only 
you can determine if such a comparison is meaningful. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


LDAP OU Condition 


The LDAP OU condition allows you to compare the DN of an OU against the DN that was used when 
the user authenticated. If the users DN contains the OU, the condition matches. 
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LDAP OU: Select [Current]. 
Comparison: Specify how you want the values compared. Select one of the following: 
+ Contains: Specifies that you want the condition to determine whether the user is contained by a 
specified organizational unit. 
+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 
Mode: Select the mode appropriate for the comparison type. 
+ Contains: Select whether the user must be contained in the specified OU (One Level) or 
whether the user can be contained in the specified OU or a child container (Subtree). 
¢ Comparison: Regular Expression: Matches: Select one or more of the following: 
Canonical Equivalence 
Case Insensitive 
Comments 
Dot All 
Multi-Line 


Unicode 
Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the second value for the comparison. If you select LDAP OU > Name of Identity 
Server Configuration > User Store Name, you can browse to the name of the OU. 


If you have more than 250 OUs defined in your tree, you are prompted to enter an LDAP query string. 
In the text box, you need to add only the <strFilter> value for the query. For example: 


<strFilter> Value Description 


admin* Returns all OUs that begin with admin, such as 
adminPR, adminBG, and adminWTH. 


*test Returns all OUs that end with test, such as doctest, 
softtest, and securtest. 


*low* Returns all OUs that have “low” in the name, such as 
low, yellow, and clowns. 

For more information about the <strFilter> parameter, see RFC 2254 “LDAP Search Filter.” 

If you select Data Entry Field, you can enter the DN of the OU in the text field. For example: 

cn=users, dc=bcf2, dc=provo, dc=novell, dc=com 

ou=users, o=novell 


If you have defined a Liberty User Profile or an LDAP attribute for the OU you want to match, select 
this option, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 
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Liberty User Profile Condition 


The Liberty User Profile condition allows you to restrict access based on a value in a Liberty User 
Profile attribute. The Liberty attributes must be enabled before you can use them in policies (click 
Devices > Identity Servers > Edit > Liberty > Web Server Provider, then enable one or more of the 
following: Employee Profile, Personal Profile). 


These attributes can be mapped to LDAP attributes (click Devices > Identity Servers > Edit > Liberty 
> LDAP Attribute Mapping). When mapped, the actual value comes from your user store. If you are 
using multiple user stores with different LDAP schemas, mapping similar attributes to the same 
Liberty User Profile attribute allows you to create one policy with the Liberty User Profile attribute 
rather than multiple policies for each LDAP attribute. 


The selected attribute is compared to a value of the following type: 


+ Roles from an identity provider 

+ Date and time and its various elements 
+ URL and its various elements 

+ IP address 

+ Authentication contract 

+ Credential profile 

+ HTTP request method 

+ LDAP attribute 

¢ Static value in a data entry field 


To set up the matching for this condition, fill in the following fields: 


Liberty User Profile: Select the Liberty User Profile attribute. These attributes are organized into two 
main groups: Corporate Employment Identity and Entire Personal Identity. By default, the Common 
Last Name attribute for Liberty User Profile is mapped to the sn attribute for LDAP. To select this 
attribute for comparison, click Entire Personal Identity > Entire Common Name > Common Analyzed 
Name > Common Last Name. 


Comparison: Select the comparison type that matches the data type of the selected attribute and the 
value. 


Mode: Select the mode, if available, that matches the data type. For example, if you select to 
compare the values as strings, you can select either a Case Sensitive mode or a Case Insensitive 
mode. 


Value: Select one of the values that is available from the current request or select Data Entry Field to 
enter a static value. The static value that you can enter is dependent upon the comparison type you 
selected. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Roles Condition 


If you have configured some Access Manager role policies (see Section 8.2.3, “Creating Roles,” on 
page 726), you can use these roles as conditions to control access. Roles are not assigned to users 
until the users authenticate. All authenticated users are assigned the authenticated role. If you use 
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a comparison type of starts with, ends with, or contains substring, carefully evaluate the potential 
results. For example, if you specify ed as the value for an ends with comparison, the condition 
matches roles such as contracted and assigned that you created, but it also matches the 
authenticated role. 


Fill in the following fields: 


Roles: Select the role. To compare the roles the user is currently assigned with a specific role, select 
[Current]. 


Comparison: Select one of the following types: 


¢ Comparison: String: Specifies that you want the values compared as strings, and how you 
want the string values compared. Select one of the following: 


¢ Equals: Indicates that the values must match, letter for letter. 


¢ Starts with: Indicates that the Roles value must begin with the letters specified in the Value 
field. 


+ Ends with: Indicates that the Roles value must end with the letters specified in the Value 
field. 


¢ Contains Substring: Indicates that the Roles value must contain the letters, in the same 
sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: If you have created Identity Server roles policies, select Roles, then select the role you want 
the user to match this condition. The authenticated role is assigned to all users when they 
authenticate. If you have defined a Liberty User Profile or an LDAP attribute for a role, you can select 
this option, then select your attribute. 


You can use the Data Entry Field option to enter the name of the role you want to test for. If you have 
activated roles from an external source, use this option to specify the name of the role. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 
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Risk Score 


You can define a condition group as part of the authorization policy that uses the risk score from 
Identity Server to protect a resource. 


1 


Specify how the current risk score is compared to the data in the Value field. You can select to do 
the comparison as an integer value or as a regular expression. For more details about regular 
expression, see “Comparison: Regular Expression: Matches:” on page 788. 


2 Specify the value as a Data Entry and enter the risk score for the rule. 


3 Specify the value to return if the rule execution results in an error. Select either False or True. 


4 Configure the actions required to be performed during evaluation of the condition group. For 


more information, see Step 7 on page 772. 
Click OK. 


8.3.4.14 OAuth Scopes 


You can define a condition group as part of the authorization policy that uses the OAuth scopes from 
Identity Server to protect a resource. 


8.3.4.15 


1 


Comparison: You can select to do the comparison as an integer value or as a regular 
expression. For more information about regular expression, see “Comparison: Regular 
Expression: Matches:” on page 788. 


Mode: Select the mode appropriate for the comparison type. For more information, see “Mode:” 
on page 785. 


Value: Select OAuth Scopes. 


4 Result on Condition Error: Specify what the condition returns when the comparison of the two 


values returns an error rather than the results of the comparison. Select either False or True. If 
you do not want the action applied when an error occurs, select False. If you want the action 
applied when an error occurs, select True. 


Configure the actions required to be performed during evaluation of the condition group. For 
more information, see Step 7 on page 772. 


Click OK. 


URL Condition 


The URL condition allows you to restrict access based on the URL specified in the request. If you 
have users requesting a resource with a URL you don’t want them to use, you can use this condition 
in an Access Gateway Authorization policy to deny them access to this URL, and use the Actions 
section to redirect the request to the URL you want them to use. 


To set up matching for this condition, fill in the following fields: 


Comparison: Specify how the URL is compared to the data in the Value field. Select one of the 
following types: 


+ 


+ 


Comparison: URL: Equals: Specifies that you want the values compared as URLs. 


Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 
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Mode: Select the mode appropriate for the comparison type: 


¢ Comparison: URL: Equals: Specify whether case is important by selecting Case Sensitive or 
Case Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


The URL query strings can also be used in comparisons. Select Regular Expression Match to 
implement it. For example, if you want to match against a query string parameter xyz, whose 
value is abc, you need to enter the following regular expression in the Data Entry field: 


"*\?.*xyz=abc.*" 


This follows the java regular expression pattern. For more information, see The API specification 
for the Java 2 Platform (https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html) 
for the Java Regular Expression syntax. 


Value: To enter a static value to compare to the URL in the current request, select Data Entry Field 
and specify the URL. This must be the complete URL, starting with the URL scheme (http:// or https:/ 
/) and including the domain name, but not the port. If the URL contains a path, you must include it. If 
you do not specify a scheme, HTTP is used. 


If you selected Regular Expression: Matches, regular expression rules apply. 


If you selected URL: Equals for your comparison type, the wildcard characters (?) or (*) can be 
specified as the last element of the URL path to aid in matching basic URL patterns. These wildcard 
characters are interpreted as follows: 

+ ? matches all files at the specified directory level 


+ *matches all files and directories at and beyond the specified directory level 


For example, if the request URL is http://www. resourcehost.com/path/resource. gif, the 
following entered URLs would match the request URL: 


http://www. resourcehost.com/path/resource. gif 
http://www. resourcehost.com/path/? 
http://www. resourcehost.com/path/* 

http://www. resourcehost.com/* 


If you selected URL:Equals for the comparison type, you can add multiple values: 


+ Use the Edit button to access a text box where you can enter multiple values, each ona 
separate line. For more information, see “Edit Button” on page 809. 

+ Use the Add button to add values one at a time. 

+ Use the URL Dredge button to display a list of links to use as values. For more information about 
this option, see Using the URL Dredge Option. 


All entered URLs are compared to the request URL until a match is found or the list is exhausted. 
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If you have defined a Liberty User Profile or an LDAP attribute for a URL, you can select these 
options for the value type, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


URL Scheme Condition 


The URL Scheme condition allows you to restrict access based on the scheme specified in the URL 
of the request. For example in an Access Gateway Authorization policy, if the request contains HTTP 
as the scheme in the URL and you require users to use HTTPS, you can use this condition to deny 
access and redirect them to another URL. 


This condition allows you to compare A to B or B to A. You need to decide whether you want to 
compare a static value to the current value in the HTTP request, or whether you want to compare the 
current value in the HTTP request to a specified value. The comparison type you use depends upon 
the value you want to specify. If you want more flexibility in specifying the value, you must select to 
compare the current value in the HTTP request with a specified value. 


To set up matching for this condition, fill in the following fields: 


URL Scheme: Specify the scheme you want compared. You can select Current for the current value 
in the HTTP request, or specify a static value of http or https. 


Comparison: Select one of the following types: 
+ Comparison: URL Scheme: Specifies that you want the values compared as scheme strings 
and how you want the values compared. Select one of the following: 


¢ Equals: Indicates that the URL scheme must contain the same letters, in the same order as 
specified in the value. 

¢ Starts with: Indicates that the URL scheme must begin with the letters specified in the 
value. 

+ Ends with: Indicates that the URL scheme must end with the letters specified in the value. 


+ Contains Substring: Indicates that the URL scheme must contain the letters, in the same 
sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: String: Specify whether case is important by selecting Case Sensitive or Case 
Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
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Value: Specify the value you want to compare with the URL Scheme value. If you select a static value 
for the URL Scheme value, select URL Scheme and Current. If you select Current for the URL 
Scheme value, select one of the following value types: 


¢ Data Entry Field: Allows you to specify the scheme value you want to use in the comparison. 
The scheme cannot be specified with a trailing colon (:) character and must be specified in 
lowercase (hitp or https). Use the Edit button to access a text box where you can enter multiple 
values, each on a separate line. (For more information, see “Edit Button” on page 809.) Use the 
Add button to add values one at a time. 


All entered URL schemes are compared to the requested URL scheme until a match is found or 
the list is exhausted. 


+ LDAP Attribute: If you have defined an LDAP attribute containing a URL or URL scheme, you 
can select this option, then select your attribute. 


¢ Liberty User Profile: If you have defined a Liberty User Profile attribute containing a URL or 
URL scheme, you can select this option, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


8.3.4.17 URL Host Condition 


The URL Host condition allows you to restrict access based on the hostname specified in the URL of 
the request. For example, you can use this condition to create rules that allow access if the URL 
contains one hostname, but deny access if the URL contains another hostname. The URL Host 
condition compares the hostname in the URL of the current request to the URL hostname specified in 
the Value field. 


To set up matching for this condition, fill in the following fields: 


Comparison: Specify how the URL Host is compared to the data in the Value field. Select one of the 
following types: 


¢ Comparison: URL Host: Equals: Specifies that you want the values compared as hostnames. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. If you select this option, you must also specify a Mode. Select one or more 
of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Select one of the following value types, then specify a value: 


¢ Data Entry Field: To specify a static value to compare to the URL host in the current request, 
select this value type and specify the DNS name of the host. 
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For example, if the request URL is http://www.resourcehost.com/path/resource.gif, the following 
hostname matches the resource URL: 


www. resourcehost.com 


If you selected URL Host:Equals for the comparison type, you can add multiple values: 


+ Use the Edit button to access a text box where you can enter multiple values, each on a 
separate line. For more information, see “Edit Button” on page 809. 


+ Use the Add button to add values one at a time. 
All listed hostnames are compared to the requested URL until a match is found or the list is 
exhausted. 


LDAP Attribute: If you have defined an LDAP attribute containing a URL or URL host, you can 
select this option, then select your attribute. 


Liberty User Profile: If you have defined a Liberty User Profile attribute containing a URL or 
URL host, you can select this option, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


URL Path Condition 


The URL Path condition allows you to restrict access based on the path specified in the URL of the 
request. This condition compares the path of the URL in the current request to the path specified in 
the Value field. 


To set up matching for this condition, fill in the following fields: 
Comparison: Select one of the following types: 


+ Comparison: URL Path: Specifies that you want the values compared as paths and how you 


want the string values compared. Select one of the following: 


¢ Equals: Indicates that the URL path must contain the same letters, in the same order as 
specified in the value. 


¢ Starts with: Indicates that the URL path must begin with the letters specified in the value. 
¢ Ends with: Indicates that the URL path must end with the letters specified in the value. 


¢ Contains Substring: Indicates that the URL path must contain the letters, in the same 
sequence, as specified in the Value field. 


¢ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 


regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: URL Path: Specify whether case is important by selecting Case Sensitive or Case 


Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 
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Multi-Line 
Unicode 
Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the value type and value for the comparison. Select one of the following: 


¢ Data Entry Field: To enter a static value to compare to the URL path in the current request, 
select this value type and specify the path. Start the path with a forward slash. 


IMPORTANT: If you need to add a space in the path, you need to enter this encoded value for 
the space: %20 


If you have selected Regular Expression: Matches for your comparison type, regular expression 
rules apply. If you have selected URL Path for your comparison type, the path can end with a 
filename or a wildcard. An asterisk (*) matches all files and directories at and beyond the 
specified directory level. A question mark (?) matches all files at the specified directory level. For 


example: 

Path Match Description 

/path1/path2/ Requires an exact match of the URL path. It matches if the URL 
does not contain anything after path2. 

/pathi/file.ext Requires an exact match of the URL path, including the extension 
on the filename. 

/path1/path2/? Matches everything that immediately follows path2. It does not 
match anything if the path contains another directory, such as / 
path1/path2/path3/file3.ext. 

/path1/path2/* Matches everything that follows path2, including a filename or 


another directory, such as /path1/path2/path3/file3.ext. 


If you selected URL Path for the comparison type, you can add multiple values: 


+ Use the Edit button to access a text box where you can enter multiple values, each on a 
separate line. For more information, see “Edit Button” on page 809. 


+ Use the Add button to add values one at a time. 
All entered URL paths are compared to the request URL path until a match is found or the list is 
exhausted. 


+ LDAP Attribute: If you have defined an LDAP attribute containing a URL or URL path, you can 
select this option, then select your attribute. 


¢ Liberty User Profile: If you have defined a Liberty User Profile attribute containing a URL or 
URL path, you can select this option, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 
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URL File Name Condition 


The URL File Name condition allows you to restrict access based on the filename specified in the 
URL. It compares the filename in the URL of the current request to the filename specified in the Value 


To set up matching for this condition, fill in the following fields: 
Comparison: Select one of the following types: 


+ Comparison: URL File: Specifies that you want the values compared as filenames and how you 


want the names compared. Select one of the following: 


¢ Equals: Indicates that the filenames must contain the same letters, in the same order as 
specified in the value. 


¢ Starts with: Indicates that the filenames must begin with the letters specified in the value. 
+ Ends with: Indicates that the filenames must end with the letters specified in the value. 


+ Contains Substring: Indicates that the filenames must contain the letters, in the same 
sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 


regular expressions. 


Mode: Select the mode appropriate for the comparison type: 


+ Comparison: URL File: Specify whether case is important by selecting Case Sensitive or Case 


Insensitive. 


Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 


Value: Specify the value type and value for the comparison. Select one of the following: 


¢ Data Entry Field: To specify a static value to compare to the filename in the current request, 


select this value type and specify the filename. 


The value you specify is compared to what follows the last slash in the URL. If you selected 
Regular Expression: Matches for your comparison type, regular expression rules apply. If you 
selected URL File for your comparison type, enter a value that matches your string comparison 
type. Do not use wildcards in your value. 


If you selected URL File for the comparison type, you can add multiple values: 


+ Use the Edit button to access a text box where you can enter multiple values, each on a 
separate line. For more information, see “Edit Button” on page 809. 


+ Use the Add button to add values one at a time. 


All listed filenames are compared to the requested URL filename until a match is found or the list 
is exhausted. 
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+ LDAP Attribute: If you have defined an LDAP attribute containing a URL or filename, you can 
select this option, then select your attribute. 


¢ Liberty User Profile: If you have defined a Liberty User Profile attribute containing a URL or 
filename, you can select this option, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


8.3.4.20 URL File Extension Condition 


The URL File Extension condition allows you to restrict access based on the file extension specified 
in the URL of the request. It compares the file extension in the URL of the current request to the 
extension specified in the Value field. 


To set up matching for this condition, fill in the following fields: 
Comparison: Select one of the following types: 
+ Comparison: URL File: Specifies that you want the values compared as file extensions and 
how you want the file extensions compared. Select one of the following: 


¢ Equals: Indicates that the file extensions must contain the same letters, in the same order 
as specified in the value. 


¢ Starts with: Indicates that the file extensions must begin with the letters specified in the 
value. 


+ Ends with: Indicates that the file extensions must end with the letters specified in the value. 


+ Contains Substring: Indicates that the file extensions must contain the letters, in the same 
sequence, as specified in the Value field. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. 


Mode: Select the mode appropriate for the comparison type: 
+ Comparison: URL File Extension: Specify whether case is important by selecting Case 
Sensitive or Case Insensitive. 


+ Comparison: Regular Expression: Matches: Select one or more of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the value type and value for the comparison. Select one of the following: 


¢ Data Entry Field: To specify a static value to compare to the file extension in the current 
request, select this value type and specify the file extension. You can specify the extension or 
the period and the extension. For example: 
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ext 
ext 


This condition does not support wildcards. If you selected URL File Extension for the 
comparison type, you can add multiple values: 


+ Use the Edit button to access a text box where you can enter multiple values, each on a 
separate line. For more information, see “Edit Button” on page 809. 


+ Use the Add button to add values one at a time. 
All entered URL file extensions are compared to the requested URL file extension until a match 
is found or the list is exhausted. 


+ LDAP Attribute: If you have defined an LDAP attribute containing a URL or file extension, you 
can select this option, then select your attribute. 


¢ Liberty User Profile: If you have defined a Liberty User Profile attribute containing a URL or file 
extension, you can select this option, then select your attribute. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


Virtual Attribute Condition 


The Virtual Attribute condition allows you to control access based on a value in an Virtual attribute. 
You can have the user's attribute value retrieved from an external source and compared to a value of 
the following type: 

+ Roles from an identity provider 

¢ Authenticating IDP or user store 

+ Authentication contract, method, or type 

¢ Credential profile 

+ LDAP attribute, OU, or group 

¢ Liberty User Profile attribute 

¢ Static value in a data entry field 

¢ Virtual Attribute 


To set up the matching for this condition, fill in the following fields: 


Virtual Attribute: Specify the virtual attribute you want to use in the comparison. Select a virtual 
attribute from the list.’ 


Comparison: Specify how you want the values compared. All data types are available. Select one 
that matches the value type of your virtual attribute. 


Mode: Select the mode, if available, that matches the comparison type. For example, if you select to 
compare the values as strings, you can select either a Case Sensitive mode or a Case Insensitive 
mode. 


Value: Specify the second value for the comparison. All data types are available. For example, you 
can select to compare the value of one virtual attribute to the value of another virtual attribute. Only 
you can determine if such a comparison is meaningful. 
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Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 
error occurs, select True. 


X-Forwarded-For IP Condition 


For added security, you can add the IP address of the reverse proxy as a condition to check before 
granting access. One way to implement this is to create a rule that requires the X-Forwarded-For IP 
address in the HTTP header to match the configured IP address of the reverse proxy that is using the 
policy. The X-Forwarded-For IP condition matches the first IP address in the X-Forwarded-For header 
with the IP address specified in the Value field. 


To set up matching for this condition, fill in the following fields: 


Comparison: Specify how the X-Forwarded-For IP address is compared to the data in the Value 
field. Select one of the following types: 


+ Comparison: IP: Specifies that you want the values compared as IP addresses. Select one of 
the following: 


¢ Equals: Allows you to specify an IP address that the X-Forwarded-For IP address must 
match. You can specify more than one. 


+ In Range: Allows you to specify a range of IP addresses that the X-Forwarded-For IP 
address must fall within. You can specify more than one range. 


+ In Subnet: Allows you to specify the subnet that the X-Forwarded-For IP address must 
belong to. You can specify more than one subnet. 


+ Comparison: Regular Expression: Matches: Specifies that you want the values compared as 
regular expressions. If you select this option, you must also specify a Mode. Select one or more 
of the following: 


Canonical Equivalence 
Case Insensitive 
Comments 

Dot All 

Multi-Line 

Unicode 

Unix Lines 


For regular expression syntax information, see the Javadoc for java.util.regex.Pattern. 
Value: Specify the value type and value for the comparison. Select one of the following: 


¢ Client IP: If you want the first IP address in the X-Forwarded-For header compared to the IP 
address of the client making the request, select this option. 


NOTE: Client IP will not support IPv6 addresses. 


+ LDAP Attribute: If you have defined an LDAP attribute for an IP address, you can select this 
option, then select your attribute. 


¢ Liberty User Profile: If you have defined a Liberty User Profile attribute for an IP address, you 
can select this option, then select your attribute. 


+ X-Forwarded-For-IP: Allows you to control access based on the value in the X-Forwarded-For 
IP header of the HTTP request. This supports IPv6 address when you use the X-Forwarded-For 
IP condition. 
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¢ Data Entry Field: To specify a static value, select Data Entry Field and provide a value 
appropriate for your comparison type. For example: 


Comparison Type IPv4 Value IPv6 Value 

Equals 10.10.10.10 2001:1000:1000:1000:1000:1000:1000:1a8a 
10.10.10.11 2001: :10a0 

In Range 10.10.10.10 - 2134::10 -2134::100 
10.10.10.100 

2134:1000:1000:1000:1000:1000:2000:1000 - 

10.10.20.10 - 2134 :1000: 1000 :1000:1000:1000: 2000: 4000 
10.10.20.100 

In Subnet 10.10.10.12 / 22 2001:1000: :0002:1000:1a8a/40 
10.10.20.30 / 22 2001: 1000: 1000: 2000: 3000: 4000: 5000: 1a8a/50 


You can now enter an IPv6 IP address. If you enter a zone ID and scope ID in an IP address with 
% sign, you will get an error. For more information see Section 9.3, “Setting up L4 Switch for 


IPv6 Support,” on page 891. 


If you selected IP for the comparison type, you can add multiple values: 


+ Use the Edit button to access a text box where you can enter multiple values, each on a 


separate line. 


+ Use the Add button to add values one at a time. 


All listed values are compared to the IP address in the X-Forwarded-For IP header until a match 
is found or the list is exhausted. 


Result on Condition Error: Specify what the condition returns when the comparison of the two 
values returns an error rather than the results of the comparison. Select either False or True. If you do 
not want the action applied when an error occurs, select False. If you want the action applied when an 


error occurs, select True. 


Condition Extension 


If you have loaded and configured an authorization condition extension, this option specifies a 
condition that is evaluated by an outside source. This outside source returns either true or false. See 
the documentation that came with the extension for information about what is evaluated. 


8.3.4.24 Data Extension 


If you have loaded and configured an authorization data extension, this option specifies the value that 
the extension retrieves. You can then select to compare this value with an LDAP attribute, a Liberty 
User Profile attribute, a Data Entry Field, or another Data Extension. For more information, see the 
documentation that came with the extension. 


In the URL to Dredge text box, enter the URL of a page on a web server, then click Display URL List. 


For example, if you enter ww.netiq.com/documentation/index.html for the URL to Dredge, links 
such as the following appear in the Links section of the URL Results list: 


8.3.4.25 Using the URL Dredge Option 
A list of links and images appears. 
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www.netiq.com/company/careers/index. html 
www.netiq.com/company/strategy.html 
www.netiq.com/documentation/netiqaccessmanager32/index.html 
www.netiq.com/documentation/netiqaccessmanager31/index.html 


Depending upon how you have configured your website, you need to enter either a target page or just 
the URL of the site to generate a list of links. 


To add all links as values to the URL condition, click Links. To add links selectively as a value, select 
the check box next to each name. To dredge a link in the list, click the link. 


If the URL contains images, a list of images appears in the Images section. To add an image as a 
value, select the check box next to the image name. 


To save your changes, click OK. 


IMPORTANT: If you attempt to dredge an HTTPS site that is using a self-signed certificate, you need 
to import the trusted root of the site into the Trusted Roots store of Access Gateway before 
performing the dredge. 


Edit Button 


Some of the conditions such as Client IP and URL display an Edit button when you select Equals as 
the condition and Data Entry Field as the value. The Edit button displays a text box where you can 
specify multiple values. 


In the text box, enter each value on a separate line. 
To save your modifications, click OK. 


To discard your modifications, click Cancel. 


Importing and Exporting Authorization Policies 


You can import and export Authorization policies to run them in other Access Manager configurations 
and to analyze the authorization logic. The policy is exported as a text file with XML tags. We do not 
recommend editing the exported file with a text editor. Any changes you want to make to a policy 
must be done through Administration Console. 


To export an Authorization policy: 


1 In Administration Console Dashboard, click Policies > Policies. 

2 Select an Authorization policy, then click Export. 

3 (Optional) Modify the name suggested for the file. 

4 Click OK. 

5 Using the features of your browser, specify where you want the file to be copied. 
6 Click OK. 


To import a policy: 


1 Ensure that any referenced Role policies have been imported. 
See Section 8.2.8, “Importing and Exporting Role Policies,” on page 760. 


2 If the policy uses LDAP or Liberty Profile attributes, ensure that Identity Server has been 
configured for these same attributes. 
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3 In Administration Console Dashboard, click Policies > Policies. 
4 Click Import, then browse to and select the file. 

5 Click OK. 

6 When the policy appears in the list, click Apply Changes. 


Identity Injection Policies 


Identity injection allows you to add information to the URL or to the HTML page before it is posted to 
a web server. The web server uses this information to determine whether the user can access to the 
resource, so it is the web server that determines the information that you need to inject to allow 
access to the resource. 


Identity injection is one of the features of Access Manager that enable you to provide single sign-on 
for your users. When the policy is configured, the user is unaware that additional information is 
required to access a web server. 


IMPORTANT: Identity Injection policies allow you to inject the user’s password into the HTTP header. 
If you set up such a policy, you must also configure Access Gateway to use SSL between itself and 
the back-end web server. This is the only way to ensure that the password is encrypted on the wire. 


This section describes the elements available for an Identity Injection policy, but your web servers 
determine which elements you use. 

¢ Section 8.4.1, “Designing an Identity Injection Policy,” on page 810 

¢ Section 8.4.2, “Configuring an Identity Injection Policy,” on page 812 

¢ Section 8.4.3, “Configuring an Authentication Header Policy,” on page 813 

e Section 8.4.4, “Configuring a Custom Header Policy,” on page 818 

¢ Section 8.4.5, “Configuring a Custom Header with Tags,” on page 820 

¢ Section 8.4.6, “Specifying a Query String for Injection,” on page 823 

¢ Section 8.4.7, “Injecting into the Cookie Header,” on page 825 

¢ Section 8.4.8, “Configuring an Inject Kerberos Ticket Policy,” on page 825 

¢ Section 8.4.9, “Configuring an OAuth Token Inject Policy,” on page 828 

¢ Section 8.4.10, “Importing and Exporting Identity Injection Policies,” on page 829 

¢ Section 8.4.11, “Sample Identity Injection Policy,” on page 830 


Designing an Identity Injection Policy 


Before setting up an Identity Injection policy, you need to know the following about your Web 
application: 


+ Does it require an authentication header? Does this header need just the username or does it 
also need the password? 


+ Does it use a custom header with custom names (x-names)? If so, you need to know their 
names and their expected values. 


+ Does the custom header require any custom names (x-names) with tags? If so, gather this 
information. 


+ Does the application expect specific values in the query string of the URL? If so, gather this 
information. 
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+ Does it require the authentication information from the Kerberos tickets? If so, gather this 
information. 


+ Does the application require Access Gateway to fetch OAuth token and pass it over to the 
header? If so, gather this information. 


After gathering the information, you need to determine whether you need to create one policy with 
one rule, one policy with multiple rules, or multiple policies. If you have multiple applications that 
require the same type of authentication header, you might want to create an authentication header 
policy and separate policies for the application-specific information. You can then enable both the 
authentication header policy and the application-specific policy for the resource that is protecting the 
application. You must design your policies so that the application receives just what it needs. It must 
not inject custom names and values it does not use. 


Everything defined in a policy is injected into the header, even if the values are empty because 
Access Manager could not obtain the value for the item. For some applications, this is still useful 
information and the application uses it to make access decisions. 


Whether you create a policy with one rule or multiple rules is a personal design decision. If you put all 
the actions in one rule, you have only one description field to describe the function of the policy. If you 
put each action type in a separate rule, you have multiple description fields to describe the function of 
the policy. Select the method that is easiest for you. 


Rules are evaluated by priority. The first rule that is evaluated with an authentication header is 
processed, and the authentication header is rejected if it is found in any of the other rules. Your policy 
can inject only one authentication header, one cookie header, and one query string, but it can inject 
multiple custom headers and custom headers with tags. 


Using the Refresh Data Option 


Identity Injection policies are processed when a user requests access to a resource. The results and 
the values of the data items are cached for the user session. This means that when the user requests 
a second time to access the resource, the policy is evaluated, but the data values from the first 
evaluation are used. When a data item is cached for the user session, the user must log out and log 
back in to trigger new data values. (For information about how long the data items are cached, see 
Section 30.6.3, “The Policy Is Using Old User Data,” on page 1230.) 


The LDAP Attribute and the Shared Secret actions can be configured to refresh their values. This 
means the attribute or secret value is read not just on the first request that triggers the policy 
evaluation, but when the specified refresh interval expires. You can select to cache the value for the 
session, for the request, or for a time interval varying from 5 seconds to 60 minutes. 


You can use this feature for situations when you do not want to force the user to log in again to gain 
rights to resources or to revoke rights to resources. For example, suppose that you have an Identity 
Injection policy that grants access based on an LDAP attribute in a custom header having a “yes” 
value. Users with a “no” value in custom header are denied access. 


If you don’t enable the Refresh Data option on this attribute in the policy, the policy is evaluated when 
the user first tries to access the resource. The value for the attribute is cached for the user session, 
and until the user logs out, that is the value that is used. 
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However, if you enable the Refresh Data option on this attribute in the policy, the policy is evaluated 
when the user first tries to access the resource. When the user sends a second request to access the 
resource and the specified interval has expired, the Refresh Data option causes the value of the 
attribute to be read again from the LDAP server. This new value is injected into the custom header, 
and any other policy that is triggered by the request and uses the new value for its policy. 


+ Ifthe value from the first request to the second request changes from no to yes, the user gets 
access to the resource. 
+ Ifthe value from the first request to the second request changes from yes to no, the user is 
denied access to the resource. 
For example: 


+ Ifthe attribute controls access to employee resources and an employee leaves, a quick change 
of this attribute value cuts the employee off from the resources that must be available to 
employees only. 


+ Ifthe attribute controls access to a software download site and a user has just purchased a 
product, a quick change to this attribute value can grant access to the download site. 


IMPORTANT: This feature needs to be used with caution. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute and secret store values are normally cached for the 

user session. Enable this option only on those attributes and secrets that are critical to the security of 
your system or to the design of your work flow. 


Configuring an Identity Injection Policy 


1 In Administration Console Dashboard, click Policies > Policies. 
2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type of policy, 
then click OK. 


4 Fill in the following fields: 


Description: (Optional) Describe the purpose of this policy. Because Identity Injection policies 
are customized to match the content of a specific web server, you might want to include the 
name of the web server as part of the description. 


Priority: Specify the order in which a rule is applied in the policy, when the policy has multiple 
rules. The highest priority is 1 and the lowest priority is 10. 


5 In the Actions section, click New, then select one of the following. 


¢ Inject into Authentication Header: Inserts the username and password into the header. 
For information about how to configure this type of policy, see Section 8.4.3, “Configuring an 
Authentication Header Policy,” on page 813. 


¢ Inject into Custom Header: Inserts custom names with values into the custom header. For 
information about how to configure this type of policy, see Section 8.4.4, “Configuring a 
Custom Header Policy,” on page 818. 


¢ Inject into Custom Header with Tags: Inserts custom tags with name/value content into 
the custom header. For information about how to configure this type of policy, see 
Section 8.4.5, “Configuring a Custom Header with Tags,” on page 820. 


¢ Inject into Query String: Inserts a query string into the URL for the page. For information 
about how to configure this type of policy, see Section 8.4.6, “Specifying a Query String for 
Injection,” on page 823. 
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¢ Inject into Cookie Header: Inserts the session cookie into the cookie header. For 
information about how to configure this type of policy, see Section 8.4.7, “Injecting into the 
Cookie Header,” on page 825. 


¢ Inject Kerberos Ticket: Inserts authentication values from the Kerberos ticket into the 
custom header. For information about how to configure this type of policy, see Section 8.4.8, 
“Configuring an Inject Kerberos Ticket Policy,” on page 825. 


+ Inject OAuth Token: Injects OAuth token into the web applications’ header as an 
authorization bearer. For information about how to configure this type of policy, see 
Section 8.4.9, “Configuring an OAuth Token Inject Policy,” on page 828. 


6 (Optional) Repeat Step 5. 


Repeat this process to add multiple actions to the same rule. If a particular action is allowed only 
once per rule, then the action does not appear in the New menu if that action has already been 
defined in the rule. If an action is allowed multiple times per rule, you can select it from the New 


menu or use the Copy Action icon l| and modify the new entry. 
7 To save the policy, click OK twice, then click Apply Changes. 


8 For information about how to assign the policy to a protected resource, see “Assigning an 
Identity Injection Policy to a Protected Resource” on page 134. 


8.4.3 Configuring an Authentication Header Policy 


To inject values into the authentication header, you need to know what the web server requires. For 
basic authentication, you need to inject the username and password. For a sample policy for a web 
server that requires the LDAP username and password to be injected into the header, see 

Section 3.6.4, “Setting Up Policies,” on page 110. 


To create and configure an authentication header policy: 


1 In Administration Console Dashboard, click Policies > Policies. 
2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type, then click 
OK. 


4 (Optional) Specify a description for the injection policy. This is useful if you plan to create multiple 
policies to be used by multiple resources. 


5 Inthe Actions section, click New, then select Inject into Authentication Header. 
6 Fill in the User Name field. 


Select Credential Profile to insert the name the user entered when the user authenticated. This 
is the most common value type to use for the username. 


The default contracts assign the cn attribute to the Credential Profile. If you have created a 
custom contract that uses credentials other than the ones listed below, do not use the Credential 
Profile as a condition. 


If your user store is an Active Directory server, the SAMAccountName attribute is used for the 
username and stored in the cn field of the LDAP Credential Profile. 


Depending upon what the user must supply for authentication, select one of the following: 


+ LDAP Credentials: If you prompt the user for a username, select this option, then select 
either LDAP User Name (the cn attribute of the user) or LDAP User DN (the fully 
distinguished name of the user). Your web server requirements determine which one you 
use. 
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+ X509 Credentials: If you prompt the user for a certificate, select this option, then select one 
of the following options depending upon your web server requirements. 


+ X509 Public Certificate Subject: Injects just the subject field from the certificate, 
which can match the DN of the user, depending upon who issued the certificate. 


+ X509 Public Certificate Issuer: Injects just the issuer field from the certificate, which 
is the name of the certificate authority (CA) that issued the certificate. 


+ X509 Public Certificate: Injects the entire certificate. 
+ X509 Serial Number: Injects the certificate serial number. 


+ SAML Credential: Although this option is available for the username, most applications 
that use SAML assertions use them for the user’s password. For the username, you must 
probably select an option that allows you to supply the user’s name, such as LDAP 
Credentials or LDAP Attribute. 


Your web server requirements determine the data type you select for the username. LDAP, 
X509, and SAML credentials are available from the Credential Profile. If you have created a 
custom contract that uses a credential other than the ones listed in the Credential Profile, you 
can select one of the following values to insert into the header as the username: 


+ Authentication Contract: Injects the URI of the authentication contract the user used for 
authentication. 


+ Client IP: Injects the IP address associated with the user. 


+ LDAP Attribute: Injects the value of the selected attribute. For Active Directory servers, 
specify the SAMAccountName attribute for the username. If the attribute you require does 
not appear in the list, click New LDAP Attribute to add the attribute. 


The Refresh Data Every option allows you to determine when to send a query to the LDAP 
server to verify the current value of the attribute. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are normally cached for the user 
session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. 


For more information, see “Using the Refresh Data Option” on page 811. 


¢ Liberty User Profile: Injects the value of the selected attribute. If no profile attributes are 
available, you have not enabled their use in Identity Server configuration. See “Managing 
Web Services and Profiles” on page 517. 


+ Proxy Session Cookie: Injects the session cookie associated with the user. 
+ Roles: Injects the roles that have been assigned to the user. 


¢ Shared Secret: Injects the username that has been stored in the selected shared secret 
store. 


You can create your own username attribute. Click New Shared Secret, specify a display 
name for the store, and Access Manager creates the store. Select the store, click New 
Shared Secret Entry, specify a name for the attribute, then click OK. The store can contain 
one name/value pair or a collection of name/value pairs. For more information, see 
Section 8.5.4, “Creating and Managing Shared Secrets,” on page 853. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the secret. Because querying slows down the processing of a policy, secret 
values are normally cached for the user session. 
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Change the value of this option from session to a more frequent interval only on those 
secrets that are critical to the security of your system or to the design of your work flow. You 
can select to cache the value for the session, for the request, or for a time interval varying 
from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data Option” 
on page 811. 


¢ Virtual Attribute: Injects the value of the selected virtual attribute. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the virtual attribute. Because querying slows down the processing of a 
policy, the virtual attribute values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


+ X-Forwarded-For IP: Injects the X-Forwarded-For IP address of the client. 


¢ String Constant: Injects a static value that you specify in the text box. This value is used by 
all users who access the resources assigned to this policy. 


+ Java Data Injection Module: Specifies the name of a custom Java plug-in, which injects 
custom values into the header. Usually, you can use either the LDAP Attribute or Liberty 
User Profile option to supply custom values, because both are extensible. For more 
information about creating a custom plug-in, see NetIQ Access Manager Developer Tools 
and Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


+ Data Extension: (Conditional) If you have installed a data extension for Identity Injection 
policies, this option injects the value that the extension retrieves. For more information 
about creating a data extension, see Access Manager SDK Sample Code (https:// 
www.netig.com/documentation/access-manager-43-developer-documentation/ 
samplecodes/main.html). 


The value type you use depends upon how you have set up the application. 


NOTE: To improve the policy's performance, configure the LDAP Attributes, Credential Profile, 
Liberty User Profile, and Shared Secret attributes to be sent with authentication. For more 
information, see “Configuring the Attributes Sent with Authentication” on page 188. 


Fill in the Password field. 


Select Credential Profile to insert the password the user entered when the user authenticated. 
This is the most common value type to use for the password. If you have created a custom 
contract that uses credentials other than the ones listed below for the password, do not use the 
Credential Profile for the password. 


+ LDAP Credentials: If you prompt the user for a password, select this option, then select 
LDAP Password. If the user's password is the same as the name of the user, you can select 
either LDAP User Name (the cn attribute of the user) or LDAP User DN (the fully 
distinguished name of the user). 


+ X509 Credentials: If you use a certificate for the password, select this option, then select 
one of the following: 


+ X509 Public Certificate Subject: Injects just the subject from the certificate, which 
can match the DN of the user, depending upon who issued the certificate. 


+ X509 Public Certificate Issuer: Injects just the issuer from the certificate, which is the 
name of the certificate authority (CA) that issued the certificate. 


+ X509 Public Certificate: Injects the entire certificate. 
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+ X509 Serial Number: Injects the certificate serial number. 


¢ SAML Credential: Injects the SAML assertion in the authentication header as the user’s 


password. 


Your web server requirements determine the data type you select for the password. LDAP, X509, 
and SAML credentials are available from the Credential Profile. You can also select one of the 
following values to insert into the header as the password: 


+ Authentication Contract: Injects the URI of a local authentication contract that the user 


used for authentication. 
Client IP: Injects the IP address associated with the user. 


LDAP Attribute: Injects the value of the selected attribute. For Active Directory servers, 
specify the SAMAccountName attribute for the username. If the attribute you require does 
not appear in the list, click New LDAP Attribute to add the attribute. 


The Refresh Data Every option allows you to determine when to send a query to the LDAP 
server to verify the current value of the attribute. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are normally cached for the user 
session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


Liberty User Profile: Injects the value of the selected attribute. 
Proxy Session Cookie: Injects the session cookie associated with the user. 
Roles: Injects the roles that have been assigned to the user. 


Shared Secret: Injects the password that has been stored in the selected shared secret 
store. 


You can create your own password attribute. Click New Shared Secret, specify a display 
name for the store, and the Access Manager creates the store. Select the store, click New 
Shared Secret Entry, specify a name for the attribute, then click OK. The store can contain 
one name/value pair or a collection of name/value pairs. For more information, see 
Section 8.5.4, “Creating and Managing Shared Secrets,” on page 853. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the secret. Because querying slows down the processing of a policy, secret 
values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
secrets that are critical to the security of your system or to the design of your work flow. You 
can select to cache the value for the session, for the request, or for a time interval varying 
from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data Option” 
on page 811. 


X-Forwarded-For IP: Injects the X-Forwarded-For IP address of the client. 
Virtual Attribute: Injects the value of the selected virtual attribute. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the virtual attribute. Because querying slows down the processing of a 
policy, the virtual attribute values are normally cached for the user session. 
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Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


¢ String Constant: Injects a static value that you specify in the text box. This value is used by 
all users who access the resources assigned to this policy. 


+ Java Data Injection Module: Specifies the name of a custom Java plug-in, which injects 
custom values into the header. Usually, you can use either the LDAP Attribute or Liberty 
User Profile option to supply custom values, because both are extensible. For more 
information about creating a custom plug-in, see NetIQ Access Manager Developer Tools 
and Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


+ Data Extension: (Conditional) If you have installed a data extension for Identity Injection 
policies, this option injects the value that the extension retrieves. For more information 
about creating a data extension, see NetIQ Access Manager Developer Tools and 
Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


The value type you use depends upon how you have set up the application. 
8 Specify the format for the value: 


Multi-Value Separator: Select a value separator, if the value type you have select is multi- 
valued. For example, Roles can contain multiple values. 


DN Format: If the value is a DN, select the format for the DN: 
+ LDAP: Specifies LDAP typed comma notation: 


cn=j smith, ou=Sales, o=novell 

+ NDAP Partial Dot Notation: Specifies eDirectory™ typeless dot notation. 
jsmith.sales.novell 

+ NDAP Leading Partial Dot Notation: Specifies eDirectory typeless leading dot notation. 
.jsmith.sales.novell 

+ NDAP Fully Qualified Partial Dot Notation: Indicates eDirectory typed dot notation. 
cn=jsmith.ou=Sales.o=novell 


+ NDAP Fully Qualified Leading Dot Notation: Indicates eDirectory typed leading dot 
notation. 


.cn=jsmith.ou=Sales.o=novell 


9 Click OK. 
10 (Optional) To add a second rule, click New in the Rule List. 


You can inject only one authentication header into an Identity Injection rule. However, your policy 
can have multiple rules. If you inject two authentication headers, each in a separate rule, the 
authentication header in the rule with the highest priority is applied, and the authentication 
header action in the second rule is ignored. 


11 To save the policy, click OK, then click Apply Changes. 
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Configuring a Custom Header Policy 


To inject values into a custom header, you need to know the name of the tag and its expected value 
type. The names are specific to the application. The names might be case sensitive. They might 
require an X- prefix. Because the requirements vary, you need to enter them in the format as 
specified by the application. For example, an application might require the following to be in the 
custom header: 


Name/Value Pair Description 

X-First_Name=givenName A first name tag with an LDAP attribute value 
X-Last_Name=sn A last name tag with an LDAP attribute value 
X-Role=sales_role A role tag with the role name as the value. 


If you create a custom header policy with these name/value pairs, the policy injects these names with 
their values into a custom header, before sending the request to the web server. 


To create such a policy: 


1 


In Administration Console Dashboard, click Policies > Policies. 


2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type, then click 


OK. 


(Optional) Specify a description for the injection policy. This is useful if you plan to create multiple 
custom header policies to be used for multiple resources. 


5 Inthe Actions section, click New, then select Inject into Custom Header. 


6 Fill in the following fields: 


Custom Header Name: Specify the name to be inserted into the custom header. These are the 
names required by your application. If your application requires the X- prefix, ensure that you 
include the prefix in this field. 


Value: Select the value required by the name. Select one of the following: 


+ Authentication Contract: Injects the URI of a local authentication contract that the user 
used for authentication. 


¢ Client IP: Injects the IP address associated with the user. 


¢ Credential Profile: Injects the credentials that the user specified at login. You can select 
LDAP Credentials, X509 Credentials, or SAML Credentials. For more information, see 
Section 8.4.3, “Configuring an Authentication Header Policy,” on page 813. 


+ LDAP Attribute: Injects the value of the selected attribute. For Active Directory servers, 
specify the SAMAccountName attribute for the username. If the attribute you require does 
not appear in the list, click New LDAP Attribute to add the attribute. 


The Refresh Data Every option allows you to determine when to send a query to the LDAP 
server to verify the current value of the attribute. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are normally cached for the user 
session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. 


For more information, see “Using the Refresh Data Option” on page 811. 
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¢ Liberty User Profile: Injects the value of the selected attribute. If no profile attributes are 
available, you have not enabled their use in Identity Server configuration. See “Managing 
Web Services and Profiles” on page 517. 


¢ Proxy Session Cookie: Injects the session cookie associated with the user. 
+ Roles: Injects the roles that have been assigned to the user. 


¢ Shared Secret: Injects a value that has been stored in the selected shared secret store. 
Select the shared secret store and the name of the value you want injected. 


You can create your own value. Click New Shared Secret, specify a display name for the 
store, and the Access Manager creates the store. Select the store, click New Shared Secret 
Entry, specify a name for the attribute, then click OK. The name you select for the attribute 
must match the Custom Header name. The store can contain one name/value pair or a 
collection of name/value pairs. For more information, see Section 8.5.4, “Creating and 
Managing Shared Secrets,” on page 853. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the secret. Because querying slows down the processing of a policy, secret 
values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
secrets that are critical to the security of your system or to the design of your work flow. You 
can select to cache the value for the session, for the request, or for a time interval varying 
from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data Option” 
on page 811. 


¢ Virtual Attribute: Injects the value of the selected virtual attribute. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the virtual attribute. Because querying slows down the processing of a 
policy, the virtual attribute values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


+ X-Forwarded-For IP: Injects the X-Forwarded-For IP address of the client. 


¢ String Constant: Injects a static value that you specify in the text box. This value is used by 
all users who access the resources assigned to this policy. 


+ Java Data Injection Module: Specifies the name of a custom Java plug-in, which injects 
custom values into the header. Usually, you can use either the LDAP Attribute or Liberty 
User Profile option to supply custom values, because both are extensible. For more 
information about creating a Java plug-in, see NetIQ Access Manager Developer Tools and 
Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/samplecodes/). 


+ Data Extension: (Conditional) If you have installed a data extension for Identity Injection 
policies, this option injects the value that the extension retrieves. For more information 
about creating a data extension, see NetIQ Access Manager Developer Tools and 
Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


NOTE: To improve the policy's performance, configure the LDAP Attributes, Credential Profile, 
Liberty User Profile, and Shared Secret attributes to be sent with authentication. For more 
information, see “Configuring the Attributes Sent with Authentication” on page 188. 


7 Specify the format for the value: 
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Multi-Value Separator: Select a value separator, if the value type you have select is multi- 
valued. For example, Roles can contain multiple values. 


DN Format: If the value is a DN, select the format for the DN: 
+ LDAP: Specifies LDAP typed comma notation. 


cn=j smith, ou=Sales, o=novell 

+ NDAP Partial Dot Notation: Specifies eDirectory typeless dot notation. 
jsmith.sales.novell 

+ NDAP Leading Partial Dot Notation: Specifies eDirectory typeless leading dot notation. 
.jsmith.sales.novell 

+ NDAP Fully Qualified Partial Dot Notation: Indicates eDirectory typed dot notation. 
cn=jsmith.ou=Sales.o=novell 


+ NDAP Fully Qualified Leading Dot Notation: Indicates eDirectory typed leading dot 
notation. 


.cn=jsmith.ou=Sales.o=novell 
8 (Optional) To add additional custom header actions, click New, then select Inject into Custom 
Header or use the Copy Action icon ‘&) and modify the new entry. 
9 To save the policy, click OK twice, then click Apply Changes. 


8.4.5 Configuring a Custom Header with Tags 


Some Web applications require more than a name and a value to be injected into the custom header. 
Sometimes they require a custom name, a tag, and a value. Sometimes the application requires a 
custom name with multiple tags and values. The Inject into Custom Header with Tags option 
provides you with the flexibility to add such values to the custom header. For example, your 
application could be expecting the following custom header with tag: 


X-Custom_Role Role=Manager 


You can inject this information by setting the Custom Header Name to X-Custom, the Tag Name to 
Role, and the Tag Value to Manager. The value can be set as a static variable or you can retrieve it 
from various sources such as a Liberty User Profile attribute or the roles assigned to the current user. 
1 In Administration Console Dashboard, click Policies > Policies. 
2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type, then click 
OK. 


4 (Optional) Specify a description for the injection policy. This is useful if you plan to create multiple 
custom header policies to be used for multiple resources. 


5 Inthe Actions section, click New, then select Inject into Custom Header with Tags. 
6 Fill in the following fields: 


Custom Header Name: Specify the name that the application expects. If your application 
requires the X- prefix, ensure that you include the prefix in this field. 


Tag Name: Specify the tag name that the application expects. 
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Tag Value: Specify the value. Select from the following data types: 


+ 


Authentication Contract: Injects the URI of a local authentication contract that the user 
used for authentication. 


Client IP: Injects the IP address associated with the user. 


Credential Profile: Injects the credentials that the user specified at login. You can select 
LDAP Credentials, > X509 Credentials, or SAML Credential. For more information, see 
Section 8.4.3, “Configuring an Authentication Header Policy,” on page 813. 


LDAP Attribute: Injects the value of the selected attribute. For Active Directory servers, 
specify the SAMAccountName attribute for the username. If the attribute you require does 
not appear in the list, click New LDAP Attribute to add the attribute. 


The Refresh Data Every option allows you to determine when to send a query to the LDAP 
server to verify the current value of the attribute. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are normally cached for the user 
session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


Liberty User Profile: Injects the value of the selected attribute. If no profile attributes are 
available, you have not enabled their use in Identity Server configuration. See “Managing 
Web Services and Profiles” on page 517. 


Proxy Session Cookie: Injects the session cookie associated with the user. 
Roles: Injects the roles that have been assigned to the user. 


Shared Secret: Injects a value that has been stored in the selected shared secret store. 
The name specified as the Tag Name must match the name of a name/value pair stored in 
the shared secret. 


You can create your own value. Click New Shared Secret, specify a display name for the 
store, and the Access Manager creates the store. Select the store, click New Shared Secret 
Entry, specify a name for the attribute, then click OK. The name must match the expected 
Tag Name. The store can contain one name/value pair or a collection of name/value pairs. 
For more information, see Section 8.5.4, “Creating and Managing Shared Secrets,” on 
page 853. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the secret. Because querying slows down the processing of a policy, secret 
values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
secrets that are critical to the security of your system or to the design of your work flow. You 
can select to cache the value for the session, for the request, or for a time interval varying 
from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data Option” 
on page 811. 


Virtual Attribute: Injects the value of the selected virtual attribute. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the virtual attribute. Because querying slows down the processing of a 
policy, the virtual attribute values are normally cached for the user session. 
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Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


+ X-Forwarded-For IP: Injects the X-Forwarded-For IP address of the client. 


¢ String Constant: Injects a static value that you specify in the text box. This value is used by 
all users who access the resources assigned to this policy. 


+ Java Data Injection Module: Specifies the name of a custom Java plug-in, which injects 
custom values into the header. Usually, you can use either the LDAP Attribute or Liberty 
User Profile option to supply custom values, because both are extensible. For more 
information about creating a custom plug-in, see NetIQ Access Manager Developer Tools 
and Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


+ Data Extension: (Conditional) If you have installed a data extension for Identity Injection 
policies, this option injects the value that the extension retrieves. For more information 
about creating a data extension, see NetIQ Access Manager Developer Tools and 
Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


NOTE: To improve the policy's performance, configure the LDAP Attributes, Credential Profile, 
Liberty User Profile, and Shared Secret attributes to be sent with authentication. For more 
information, see “Configuring the Attributes Sent with Authentication” on page 188. 


7 To add multiple tag and value pairs to the custom name, click New in the Tags section. 
Use the up-arrow and down-arrow buttons to order the tags. 
8 Specify the format for the value: 


Multi-Value Separator: Select a value separator, if the value type you have select is multi- 
valued. For example, Roles can contain multiple values. 


DN Format: If the value is a DN, select the format for the DN: 
+ LDAP: Specifies LDAP typed comma notation. 


cn=jsmith, ou=Sales, o=novell 

+ NDAP Partial Dot Notation: Specifies eDirectory typeless dot notation. 
jsmith.sales.novell 

+ NDAP Leading Partial Dot Notation: Specifies eDirectory typeless leading dot notation. 
.jsmith.sales.novell 

+ NDAP Fully Qualified Partial Dot Notation: Indicates eDirectory typed dot notation. 
cn=jsmith.ou=Sales.o=novell 


+ NDAP Fully Qualified Leading Dot Notation: Indicates eDirectory typed leading dot 
notation. 


.cn=jsmith.ou=Sales.o=novell 


9 (Optional) To add additional custom header actions, click New, then select Inject into Custom 
Header with Tags or use the Copy Action icon | and modify the new entry. 


10 To save the policy, click OK twice, then click Apply Changes. 
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8.4.6 


Specifying a Query String for Injection 


Some applications require custom information in a query string of the URL. The Inject into Query 
String option allows you to inject this information without prompting the user for it. To inject the 
information, you must specify a tag name and a tag value. The tag name is what your application 
requires. For example, suppose your application expects the following query string for user jsmith: 


?name=j smith 


You can inject this information into the URL by specifying a name for the Tag Name and Credential 
Profile for the Tag Value. The Credential Profile value type inserts the name that the current user 
specified when authenticating to Access Gateway. 


1 


In Administration Console Dashboard, click Policies > Policies. 


2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type, then click 


OK. 


4 (Optional) Specify a description for the injection policy. 


5 In the Actions section, click New, then select Inject into Query String. 


6 Fill in the following fields: 


Tag Name: Specify the tag name that the application expects. 


Tag Value: Specify the value. Select from the following data types: 


+ 


Authentication Contract: Injects the URI of a local authentication contract that the user 
used for authentication. 


Client IP: Injects the IP address associated with the user. 


Credential Profile: Injects the credentials that the user specified at login. You can select 
LDAP Credentials, > X509 Credentials, or SAML Credential. For more information, see 
Section 8.4.3, “Configuring an Authentication Header Policy,” on page 813. 


LDAP Attribute: Injects the value of the selected attribute. For Active Directory servers, 
specify the SAMAccountName attribute for the username. If the attribute you require does 
not appear in the list, click New LDAP Attribute to add the attribute. 


The Refresh Data Every option allows you to determine when to send a query to the LDAP 
server to verify the current value of the attribute. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are normally cached for the user 
session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


Liberty User Profile: Injects the value of the selected attribute. If no profile attributes are 
available, you have not enabled their use in Identity Server configuration. See “Managing 
Web Services and Profiles” on page 517. 


Proxy Session Cookie: Injects the session cookie associated with the user. 
Roles: Injects the roles that have been assigned to the user. 


Shared Secret: Injects a value that has been stored in the selected shared secret store. 
The name specified as the Tag Name must match the name of a name/value pair stored in 
the shared secret. 
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You can create your own value. Click New Shared Secret, specify a display name for the 
store, and the Access Manager creates the store. Select the store, click New Shared Secret 
Entry, specify a name for the attribute, then click OK. The name you specify must match the 
Tag Name. The store can contain one name/value pair or a collection of name/value pairs. 
For more information, see Section 8.5.4, “Creating and Managing Shared Secrets,” on 
page 853. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the secret. Because querying slows down the processing of a policy, secret 
values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
secrets that are critical to the security of your system or to the design of your work flow. You 
can select to cache the value for the session, for the request, or for a time interval varying 
from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data Option” 
on page 811. 


¢ Virtual Attribute: Injects the value of the selected virtual attribute. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the virtual attribute. Because querying slows down the processing of a 
policy, the virtual attribute values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


+ X-Forwarded-For IP: Injects the X-Forwarded-For IP address of the client. 


¢ String Constant: Injects a static value that you specify in the text box. This value is used by 
all users who access the resources assigned to this policy. 


+ Java Data Injection Module: Specifies the name of a custom Java plug-in, which injects 
custom values into the header. Usually, you can use either the LDAP Attribute or Liberty 
User Profile option to supply custom values, because both are extensible. For more 
information about creating a custom plug-in, see NetIQ Access Manager Developer Tools 
and Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


+ Data Extension: (Conditional) If you have installed a data extension for Identity Injection 
policies, this option injects the value that the extension retrieves. For more information 
about creating a data extension, see NetIQ Access Manager Developer Tools and 
Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


NOTE: To improve the policy's performance, configure the LDAP Attributes, Credential 
Profile, Liberty User Profile, and Shared Secret attributes to be sent with authentication. For 
more information, see “Configuring the Attributes Sent with Authentication” on page 188. 


7 (Optional) To add multiple tag and value pairs, click New in the Tags section. 


You can inject only one query string into a rule, but you can inject multiple tag-name and tag- 
value pairs in the single query string. 


Use the up-arrow and down-arrow buttons to order the tags. 
8 Specify the format for the values: 


Multi-Value Separator: Select a value separator, if the value type you have select is multi- 
valued. For example, Roles can contain multiple values. 


824 Access Manager Policies 


8.4.7 


8.4.8 


DN Format: If the value is a DN, select the format for the DN: 


+ 


LDAP: Specifies LDAP typed comma notation. 

cn=jsmith, ou=Sales, o=novell 

NDAP Partial Dot Notation: Specifies eDirectory typeless dot notation. 
jsmith.sales.novell 

NDAP Leading Partial Dot Notation: Specifies eDirectory typeless leading dot notation. 
.jsmith.sales.novell 

NDAP Fully Qualified Partial Dot Notation: Indicates eDirectory typed dot notation. 
cn=jsmith.ou=Sales.o=novell 


NDAP Fully Qualified Leading Dot Notation: Indicates eDirectory typed leading dot 
notation. 


.cn=jsmith.ou=Sales.o=novell 


9 To save the policy, click OK twice, then click Apply Changes. 


Injecting into the Cookie Header 


Some applications require access to Access Gateway session cookie and expect to find it in the 
cookie header. You can create an Identity Injection policy that adds this cookie to the cookie header. 


1 In Administration Console Dashboard, click Policies > Policies. 


2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type, then click 


OK. 


4 (Optional) Specify a description for the injection policy. 


5 Inthe Actions section, click New, then select Inject into Cookie Header. 


This action allows only one value unless you have installed a data extension. If you have 
installed a data extension, you can select either Proxy Session Cookie or the Data Extension. 


Proxy Session Cookie: Injects the session cookie for the user. 


Data Extension: Injects the value retrieved from the extension. For more information about 
creating a data extension, see NetIQ Access Manager Developer Tools and Examples (https:// 
www.netig.com/documentation/access-manager-43-developer-documentation/). 


6 To save the policy, click OK twice, then click Apply Changes. 


Configuring an Inject Kerberos Ticket Policy 


This policy allows the authentication information in the Kerberos tickets to be passed to Access 


Gateway. 


To create and configure an Inject Kerberos Ticket policy, perform the following steps: 


1 In Administration Console Dashboard, click Policies > Policies. 


2 Select the policy container, then click New. 


3 Specify a name for the policy, select Access Gateway: Identity Injection for the type, then click 


OK. 
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4 (Optional) Specify a description for the injection policy. This is useful if you plan to create multiple 
policies to be used by multiple resources. 


5 Inthe Actions section, click New, then select Inject Kerberos Ticket. 
6 Select an appropriate option in User Name. 
Select Credential Profile to insert the name a user enters during the authentication process. 


This is the most common value. The default contracts assign the cn attribute to the Credential 
Profile. 


If your user store is an Active Directory server, the SAMAccountName attribute is used for the 
username and stored in the cn field of the LDAP Credential Profile. 


Depending upon what a user must supply for authentication, select one of the following: 


+ LDAP Credentials: If you prompt the user for a username, select this option. Then select 
either LDAP User Name (the cn attribute of the user) or LDAP User DN (the fully 
distinguished name of the user). Your web server requirements determine which one you 
use. 


+ X509 Credentials: If you prompt the user for a certificate, select this option. Then select 
one of the following options depending upon your web server requirements: 


+ X509 Public Certificate Subject: Injects the subject field from the certificate, which 
can match the DN of the user, depending upon who issued the certificate. 


+ X509 Public Certificate Issuer: Injects the issuer field from the certificate, which is 
the name of the certificate authority (CA) that issued the certificate. 


+ X509 Public Certificate: Injects the entire certificate. 
+ X509 Serial Number: Injects the certificate serial number. 


+ SAML Credential: Although this option is available for the username, most applications 
that use SAML assertions, use them for the user’s password. For the username, select an 
option that allows you to supply the user’s name, such as LDAP Credentials or LDAP 
Attribute. 


Your web server requirements determine the data type you select for the username. LDAP, 
X509, and SAML credentials are available from the Credential Profile. If you have created a 
custom contract that uses a credential other than the ones listed in the Credential Profile, you 
can select one of the following values to insert into the Kerberos ticket as the username: 


+ Authentication Contract: Injects the URI of the authentication contract the user specified 
for authentication. 


¢ Client IP: Injects the IP address associated with the user. 


+ LDAP Attribute: Injects the value of the selected attribute. For Active Directory servers, 
specify the SAMAccountName attribute for the username. If the attribute you require does 
not appear in the list, click New LDAP Attribute to add the attribute. 


The Refresh Data Every option allows you to determine when to send a query to the LDAP 
server to verify the current value of the attribute. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are cached for a user session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. 


For more information, see “Using the Refresh Data Option” on page 811. 


¢ Liberty User Profile: Injects the value of the selected attribute. If no profile attributes are 
available, you have not enabled their use in Identity Server configuration. See “Managing 
Web Services and Profiles” on page 517. 


Access Manager Policies 


+ Proxy Session Cookie: Injects the session cookie associated with the user. 
¢ Roles: Injects the roles that have been assigned to the user. 


¢ Shared Secret: Injects the username that has been stored in the selected shared secret 
store. 


You can create your own username attribute. 


1. Click New Shared Secret, specify a display name for the store, and Access Manager 
creates a store. 


2. Select the store, click New Shared Secret Entry, specify a name for the attribute, then 
click OK. 


The store can contain one name/value pair or a collection of name/value pairs. For 
more information, see Section 8.5.4, “Creating and Managing Shared Secrets,” on 
page 853. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the secret. Because querying slows down the processing of a policy, secret 
values are cached for a user session. 


Change the value of this option from session to a more frequent interval only on those 
secrets that are critical to the security of your system or to the design of your work flow. You 
can select to cache the value for the session, for the request, or for a time interval varying 
from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data Option” 
on page 811. 


¢ Virtual Attribute: Injects the value of the selected virtual attribute. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the virtual attribute. Because querying slows down the processing of a 
policy, the virtual attribute values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


+ X-Forwarded-For IP: Injects the X-Forwarded-For IP address of the client. 


¢ String Constant: Injects a static value that you specify in the text box. This value is used by 
all users who access the resources assigned to this policy. 


¢ Data Extension: (Conditional) If you have installed a data extension for Identity Injection 
policies, this option injects the value that the extension retrieves. For more information 
about creating a data extension, see NetIQ Access Manager Developer Tools and 
Examples (https://www.netiq.com/documentation/access-manager-43-developer- 
documentation/). 


The value type you use depends upon your application setup. 
7 Specify values in the following fields: 
Domain: Select one of the following: 


+ LDAP Attribute: When the user is authenticated at the Identity Serer by using a Kerberos 
authentication. This attribute uses userPrincipalName of the user from Active directory. 


¢ String Constant: When the user is authenticated at Identity Server by using a non- 
Kerberos authentication. If the required domain is not available in any LDAP attribute, the 
administrator can specify the domain name manually. 


Target Host: Select from request: Selects the web server FQDN that user has configured 
while configuring web servers of the proxy service. 
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Multi-Value Separator: Select a value separator, if the value type you have select is multi- 
valued. For example, Roles can contain multiple values. 


DN Format: If the value is a DN, select the format for the DN: 
+ LDAP: Specifies LDAP typed comma notation: 


cn=j smith, ou=Sales, o=novell 

+ NDAP Partial Dot Notation: Specifies eDirectory™ typeless dot notation. 
jsmith.sales.novell 

+ NDAP Leading Partial Dot Notation: Specifies eDirectory typeless leading dot notation. 
.jsmith.sales.novell 

+ NDAP Fully Qualified Partial Dot Notation: Indicates eDirectory typed dot notation. 
cn=jsmith.ou=Sales.o=novell 


+ NDAP Fully Qualified Leading Dot Notation: Indicates eDirectory typed leading dot 
notation. 


.cn=jsmith.ou=Sales.o=novell 


8 Click OK. 
9 (Optional) To add a second rule, click New in the Rule List. 


You can inject only one Kerberos ticket into an Identity Injection rule. However, your policy can 
have multiple rules. If you inject two Kerberos tickets, each in a separate rule, the Kerberos ticket 
in the rule with the highest priority is applied. The Kerberos ticket action in the second rule is 
ignored. 


10 Click OK > Apply Changes. 


Configuring an OAuth Token Inject Policy 


This policy allows Access Gateway to inject OAuth token into web applications’ header as an 
authorization bearer. 


To create and configure an OAuth Token policy, perform the following steps: 


1 Click Policies > Policies. 
2 Select the policy container. 
3 Click New, specify a name for the policy. Select Access Gateway: Identity Injection from the list, 


then click OK. 


(Optional) Specify a description for the injection policy. This is useful if you plan to create multiple 
policies to be used by multiple resources. 


5 Inthe Actions section, click New > Inject OAuth Token. 
6 You can select OAuth scope from the Available OAuth Scopes list. You can add multiple scopes 


using this option.The selected scopes get listed in the OAuth Scopes (Select from available 
OAuth Scopes list) field. If you want to manually add more scopes or edit existing scopes, you 
can use the OAuth Scopes (Select from available OAuth Scopes list) field. 


NOTE: The scopes are case-sensitive and have a character limit of 60. You can specify more 
than one scope separated by a comma. 


In the Renew Before the Token Expiry (minutes) field, specify a time for the token renewal. 
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Examples: 


Let suppose Identity Server contract time out is set for 60 minutes. Now, if you specify the 
Renew Before the Token Expiry (minutes) as 30, then the token gets renewed 30 minutes (60- 
30 minutes) after the start of Identity Server session. 


Let suppose Identity Server contract time out is set for 60 minutes. Now, if you specify the 
Renew Before the Token Expiry (minutes) also as 60, then there will be a new token issued for 
each session. 


IMPORTANT: For efficient policy execution, it is not recommended to add multiple actions with 
Inject OAuth Token policy. However, if you still add another action, then the token renewal time 
will be considered based on the lowest time amongst all the actions. 


For example, if you set the Renew Before the Token Expiry (minutes) as 30 and add Inject 
Kerberos Ticket policy with Refresh Data Every as 10 minutes, then, the token will be renewed 
at 10 minutes, instead of 30. 


8 To save the policy, click OK twice, then click Apply Changes. 


8.4.10 Importing and Exporting Identity Injection Policies 


You can import and export Identity Injection policies to run them in other Access Manager 
configurations. The policy is exported as a text file with XML tags. 


NOTE: We do not recommend editing the exported file with a text editor. Any changes you want to 
make to a policy must to be done through Administration Console. 


To export an Identity Injection policy: 


In Administration Console Dashboard, click Policies > Policies. 
Select the policy container. 
Select an Identity Injection policy, then click Export. 


Click OK. 


1 

2 

3 

4 (Optional) Modify the name suggested for the file. 

5 

6 Using the features of your browser, specify where the file is to be copied. 


To import a policy: 
1 Ensure that any referenced shared secret stores have been created. See Section 8.5.4, 
“Creating and Managing Shared Secrets,” on page 853. 


2 If the policy uses LDAP or Liberty Profile attributes, ensure that Identity Server has been 
configured for these same attributes. 


3 Ensure that any referenced role policies have been imported. 

See Section 8.2.8, “Importing and Exporting Role Policies,” on page 760. 
Click Policies. 

Click Import, then browse to the location of the file. 

Click OK. 

When the policy appears in the list, click Apply Changes. 


N © RA 
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8.4.11 Sample Identity Injection Policy 


One of the common uses of an Identity Injection policy is to differentiate between internal users and 
external users. web servers that have been configured for this logic can then display one set of pages 
to internal users and another set of pages to external users. The following sample policy is based on 
an environment that has the following characteristics: 


+ The web server has been configured to look for a custom tag called IPAddress and to 
differentiate between internal IP addresses and external IP addresses. 
+ The internal customers have NAT IP addresses. 


+ The protected resource is a page called mycompany .htm1. This page is a public protected 
resource (no authentication required) because the IP address of the client is available before 
authentication. 


To configure your site for this type of policy: 


1 In Administration Console Dashboard, click Policies > Policies. 
2 Select the policy container. 


3 Click New, specify a name for the policy, select Access Gateway: Identity Injection for the type, 
then click OK. 


4 In the Actions section, click New > Inject into Custom Header. 
5 Fill in the following fields: 
Custom Header Name: Specify IPAddress in the text box. 
Value: Select Client IP. 
The other fields do not need to be modified. Your policy must look similar to the following: 


Type: Access Gateway: Identity Injection 


Description: |P Address header injection 


Priority: 1 & 


Actions 


New wv 


Do Inject into Custom Header 
Custom Header Name: 
IPAddress 


Value; Client IP w 


Multi-Value Separator; ,¥ 


DN Format: LDAP (ex, cn=jsmith,ou=Sales,o=Novell] w 


Changes made on this panel must be applied from the Policies Panel. 
OK | Cancel | 


6 Click OK twice, then click Apply Changes. 


7 Assign the policy to the mycompany .html page of the web server. Click Access Gateways > Edit 
> [Name of Reverse Proxy] > [Name of Proxy Service] > Protected Resources. 
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8 In the Protected Resource List, select the protected resource for the page or click New to create 
one, then specify a name for it. 


9 In the URL Path List, ensure that the path ends with the name of the page. For example: 
/mycompany .htm1l 


10 Click Identity Injection, select the name of the IP address policy, then click Enable. 
11 To save the changes, click Configuration Panel > OK. 
12 On the Configuration page, click OK, then click Update. 


13 Configure the web server to use the IPAddress values in the custom header to distinguish 
between external and internal customers. 


In this sample scenario, the web server is configured to recognize IP addresses starting with 10. 
as internal customers and all other addresses as external customers. 


8.5 Form Fill Policies 


A Form Fill policy allows you to pre-populate fields in a form on first login and then save the 
information in the completed form to a secret store for subsequent logins. The user is prompted to 
reenter the information only when something changes such as when a password expires. Form Fill is 
one of the features of Access Manager that enable you to provide single sign-on for your users. 


The HTML page determines the requirements for the Form Fill policy. 


NOTE: Form Fill policies support only content-type text/html. Ensure that you configure Form Fill 
policies only for such resources. 


This section describes the following: 


e Section 8.5.1, “Understanding an HTML Form,” on page 832 

¢ Section 8.5.2, “Creating a Form Fill Policy for the Sample Form,” on page 834 

¢ Section 8.5.3, “Implementing Form Fill Policies,” on page 837 

¢ Section 8.5.4, “Creating and Managing Shared Secrets,” on page 853 

¢ Section 8.5.5, “Importing and Exporting Form Fill Policies,” on page 855 

¢ Section 8.5.6, “Configuring a Form Fill Policy for Forms With Scripts,” on page 856 
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Understanding an HTML Form 


The following figure is an example of a web page containing an HTML form: 


Figure 8-26 Sample HTML Form 


Username: 

Password: 

City of 

Employment: 

Web server: — Choose aserver— YV 
O Admin 

Please specify O Engineer 

your role: O Manager 
© Guest 

a ' O Mail 

ee petty C Payroll 

rO e LOOMIS D Self-service 


The information in this section uses this sample form to explain how to create a policy. This sample 
form contains a variety of field types: 

¢ Input items for Username and Password 

¢ Selection options for the web server field 

¢ Radio buttons for the role 

e Check boxes for single sign-on 


While analyzing a form, you need to decide if you want the policy to fill in all fields or only some of 
these. Then to look at the source HTML of the form to discover the names and types of fields. 


An HTML form is created using a set of HTML tags. A form consists of elements such as fields, 
menus, check boxes, radio buttons, and push buttons that control how the form is completed and 
submitted. For more information about forms, see the Forms section at www.w3.org (http:// 
www.w3.org/TR/html401/interact/forms.html). 


The following HTML data corresponds to the sample form (see Figure 8-26). The lines that contain 
the information needed to create a Form Fill policy appear in bold type. Each line corresponds to a 
field in the form that requires information or allows the user to select information. 
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In this example, each bold line contains information about a field, its name, and type. Use this 
information in the policy to specify how the information in the field is filled. 


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
"http: //www.w3.org/TR/htm14/loose.dtd"> 
<html> 
<head> 
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
<title>Form Fill Test Page</title> 
</head> 
<body> 
<form name="mylogin" action="validatepassword.php" method="post" 
id="mylogin"> 
<table align="center" border="0" cellpadding="4" cellspacing="4"> 
<tr align="center" valign="top"> 
<td> 
<p align="center"><font size="5">Novell Services Login 
</font></p> 
<table align="center" border="0"> 


<tr align="left"> 

<td>Username: </td> 

<td><input type="text" name="username" size="30"></td> 
</tr> 


<tr align="left"> 
<td>Password: </td> 
<td><input type="password" name="password" size="30"> 
</td> 

</tr> 


<tr align="left"> 

<td>City of<br>Employment:</td> 

<td><input type="text" name="city" size="30"></td> 
</tr> 


<tr align="left"> 
<td>wWeb server:</td> 
<td> 
<select name="webserv" size="1"> 
<option value="default" selected> 
--- Choose a server --- 
</option> 
<option value="Human Resources"> 
Human Resources 
</option> 
<option value="Development"> 
Development 
</option> 
<option value="Accounting"> 
Accounting 
</option> 
<option value="Sales"> 
Sales 
</option> 
</select> 
</td> 
</tr> 
<tr> 
<td colspan="2" align="left" height="25" valign="top"> 
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<p></p> 
</td> 
</tr> 


<tr align="left"> 
<td>Please specify<br>your role:</td> 


<td> 
<input name="role" value="admin" type="radio"> 
Admin<br> 
<input name="role" value="engineer" type="radio"> 
Engineer<br> 
<input name="role" value="manager" type="radio"> 
Manager<br> 
<input name="role" value="guest" type="radio">Guest 
</td> 
</tr> 
<tr> 


<td colspan="2" align="left" height="25" valign="top" 
width="121"> 
<p></p> 
</td> 
</tr> 


<tr align="left"> 
<td>Single Sign-on<br>to the following:</td> 
<td> 
<input name="mail" type="checkbox">Mail<br> 
<input name="payroll" type="checkbox">Payroll<br> 
<input name="selfservice" type="checkbox"> 
Self -service<br> 
</td> 
</tr> 
</table> 
</td> 
</tr> 


<tr> 
<td colspan="2" align="center"> 
<input value="Login" type="Submit"> 
<input type="reset"> 
</td> 
</tr> 
</table> 
</form> 
</body> 
</html> 


8.5.2 Creating a Form Fill Policy for the Sample Form 


The sample form has ten input fields and five selection options that need to be configured in the Form 
Fill policy. The following steps explain how to create a shared secret to store the values and use that 
shared secret to create a Form Fill policy for this sample form. For information about configuring the 
form fill policy for a complicated form with JavaScript, see Section 8.5.6, “Configuring a Form Fill 
Policy for Forms With Scripts,” on page 856. 


1 In Administration Console Dashboard, click Policies > Policies. 
2 Select the policy container, then click New. 
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Specify a display name for the policy and select Access Gateway: Form Fill for its type. 


4 (Optional) Specify a description for the Form Fill policy. This is useful if you plan to create 


multiple Form Fill policies. 


You might want to specify the name of the HTML page that contains the form this policy is 
designed to fill. 


5 In the Actions section, click New, then select Form Fill. 


6 In the Form Selection section, select Form Name and specify mylogin in the text box. The form 


name comes from the HTML page. See the following line in the source for the page: 


<form name="mylogin" action="validatepassword.php" method="post" 
id="mylogin"> 


In the Fill Options section, specify all the input fields and select options. For each new field, click 
New. Specify the fields in the order in which they appear on the form. For items that are not 
available in the other data types such as an LDAP or Liberty attribute, create shared secrets to 
store the value. 


The following table displays the Fill Options selected for each input field: 


Form Name Fill Options 


username Input Field Name: username 

Input Field Type: Text 

Input Field Value: Credential Profile: LDAP Credentials: LDAP User Name 
password Input Field Name: password 

Input Field Type: Password 

Input Field Value: Credential Profile: LDAP Credentials: LDAP Password 
webserv Input Field Name: webserv 

Input Field Type: Select 

Input Field Value: Shared Secret: sampleLogin: webserv 


To create this shared secret, click New Shared Secret, specify sampleLogin, 
then click OK. Select sampleLogin, click New Shared Secret Entry, specify 
websery, then click OK. 


For more information, see Section 8.5.4, “Creating and Managing Shared 
Secrets,” on page 853. 


To add more entries to the same secret store, such as role and mail, you need 
to manage the secrets from Identity Server. Save your draft of the policy, then 
click Devices > Identity Servers > Shared Settings > Custom Attributes. 
Select the name of your secret store (in this example it is sampleLogin). Add 
the entries you need for role, mail, payroll, and selfservice. These names need 
to match the form name. 


role Input Field Name: role 
Input Field Type: Radio Button 


Input Field Value: Shared Secret: sampleLogin: role 
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Form Name Fill Options 


mail Input Field Name: mail 

Input Field Type: Checkbox 

Input Field Value: Shared Secret: sampleLogin: mail 
payroll Input Field Name: payroll 

Input Field Type: Checkbox 

Input Field Value: Shared Secret: sampleLogin: payroll 
selfservice Input Field Name: selfservice 

Input Field Type: Checkbox 


Input Field Value: Shared Secret: sampleLogin: selfservice 


In the Submit Options section, fill in the following fields: 


Auto Submit: Select this option to submit the form as soon as all the values are filled in. If this 
option is not selected, even though all the values are filled in for the user, the user must click the 
Submit button. 


Debug Mode: Select the Debug Mode option, which allows you to verify that the information is 
correct before submitting the form. If values must be filled in, you first see the form to add the 
values. When the form is submitted, you are presented with a JavaScript that contains all of the 
name/value pairs. To submit the form, you need to click the Submit button. 


Insert Text in Header: Select this option so you can add a static value. In the Text to Insert box, 
specify the city value. 

city = Provo 

To create a login failure policy, click New in the Actions section, then select Form Login Failure. 


In the Form Selection section, select Form Name and specify mylogin in the text box. The form 
name comes from the HTML page. 


In the Login Failure Processing section, fill in the following field: 


Clear Shared Secret Data Values from Policy: Select this option to clear the data stored in the 
Shared Secret object when login fails. Select the name you have given to this policy. 


Use the up-arrow button to move the Form Login Failure policy to the top of the policy list. 
You want the failure policy to execute first on login failure. 


To create an Inject JavaScript policy, click New in the Actions section, then select Inject 
JavaScript. This option adds the configured JavaScript to a HTML page and is available only in 
interactive mode. For more information about creating an Inject JavaScript policy, see “Creating 
an Inject JavaScript Policy” on page 848. 


In the Configure Javascripts section, select the option where you want the JavaScript inserted in 
the HTML page. 


Click OK. 
On the Policies page, click Apply Changes. 
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8.5.3.1 


Implementing Form Fill Policies 


Section 8.5.2, “Creating a Form Fill Policy for the Sample Form,” on page 834 section describes how 
to create a simple Form Fill policy for a few input fields. This section describes all available options 
and explains how to use them to create a Form Fill policy and a Login Failure policy. 

¢ Section 8.5.3.1, “Designing a Form Fill Policy,” on page 837 

¢ Section 8.5.3.2, “Creating a Form Fill Policy,” on page 841 

¢ Section 8.5.3.4, “Creating a Login Failure Policy,” on page 847 

¢ Section 8.5.3.5, “Creating an Inject JavaScript Policy,” on page 848 

¢ Section 8.5.3.6, “Troubleshooting a Form Fill Policy,” on page 851 


Designing a Form Fill Policy 


Besides analyzing the form and determining the data items that need to be filled (see Section 8.5.1, 
“Understanding an HTML Form,” on page 832), you need to consider the following when designing 
the Form Fill policy: 


¢ “Verifying the Content or Page Type of the Form” on page 837 
¢ “Creating a Form Matching Rule” on page 837 

¢ “Including JavaScript in a Form Fill Policy” on page 840 

+ “Form Fill Character Sets (UTF-8)” on page 841 


Verifying the Content or Page Type of the Form 


When configuring the protected resource that uses a Form Fill policy, the URL in the URL Path List 
must include the filename of the page that contains the form. Sometimes this is not possible. If the 
URL references a directory, Access Gateway has to parse the files that match the URL and determine 
which one contains the form. 


Access Gateway Appliance checks the files for the following content types: 


text/html 

text/xml 

text/css 

text/javascript 
application/javascript 
application/x-javascript 


If a file has no content type or has a type other than one in the above list, Access Gateway Appliance 
skips the file. 


Access Gateway Service does not check for content type; it just parses the files that match the URL. 


Creating a Form Matching Rule 


To create a successful Form Fill policy, you need to create a matching rule that matches the policy to 
the HTML page that contains the form, and then matches the form on the page. Access Gateway 
uses the following rules, in the order listed, when determining whether a page contains the required 
form: 


1. Matches the protected resource path in the URL with the page. If they don’t match, the page is 
rejected. If they match, continues. For more information, see “Using the URL of the Protected 
Resource” on page 838. 
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2. Checks for CGI criteria. If they don’t match, the page is rejected. If they match or no criteria is 
specified, continues. For more information, see “Using CGI Matching Criteria” on page 838. 


3. Checks for page matching criteria. If they don’t match, the page is rejected. If they match or no 
page matching criteria is specified, continues. For more information, see “Using Page Matching 
Criteria” on page 838. 


4. Checks the form name criteria (which can be the <FORM> name attribute, the <FORM> ID attribute, 
or a number). If it does not’ match, the page is rejected. If it matches, the form is processed. For 
more information, see “Using Form Name Criteria” on page 839. 


When Access Gateway uses URL or CGI criteria, it can make a match early in the filling process. This 
allows Access Gateway to fill the data from the web server and send it, almost simultaneously, to the 
browser. However, if Access Gateway is configured to use page matching criteria, Access Gateway 
must retrieve the entire page from the web server, process it, and then determine whether the page 
needs to fill a form. All this processing must be completed before Access Gateway can send any data 
to the browser. Unless the page is quite small, users will clearly perceive the delay. 


The form name matching criteria are not used for page matching. They are used to determine which 
form on the page is selected. Use the following methods to match the page and the form: 

¢ Using the URL of the Protected Resource 

¢ Using CGI Matching Criteria 

+ Using Page Matching Criteria 

+ Using Form Name Criteria 


Using the URL of the Protected Resource 


When you assign a Form Fill policy to a protected resource, we recommend that the URL specified in 
the URL Path List contain the filename of the page. Usually, such a URL is enough to match the 
HTML page for the form. However, when pages are dynamically generated, the same filename is 
sometimes used to display different pages. Sometimes you can’t specify the filename in the URL. 
When this is the case, you need to use either the CGI Matching Criteria or the Page Matching Criteria 
to create an accurate page matching rule. 


Using CGI Matching Criteria 


If the page for the URL changes with the CGI portion of the URL (the portion that follows the question 
mark (?) and also called the query string), you can enter the CGI value. For example, consider the 
following URL: 


http: //webaccess.novell.com/servlet/webacc?Action=User . logout 


If this is your URL, you can enter Action=User. logout as the value in the text box for the CGI 
Matching Criteria option. If the page generated from this URL always contains the page you want to 
match, you do not need to add any additional page matching criteria. 


Using Page Matching Criteria 


If your URL of your protected resource has the following characteristics, you need to use page 
matching criteria: 


+ The URL does not contain any CGI data. 


+ The URL displays generated pages that vary in content. For example, if your form fill login page 
and the login failure page share the same URL, you need to use page matching criteria. 
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Page matching criteria are the most processing-intense form of matching and must be avoided if 
possible, but sometimes they are the only method available to identify the page with the correct form. 
For example, suppose you have a login failure page and login page that use the same URL, with no 
CGI data. You can use page matching criteria to ensure that Access Gateway matches the Form Fill 
policies for login and for login failure to the correct pages. You need to examine the source code for 
each page, and identify a string at the top of the page that uniquely identifies the page. 


For example, the login page might contain a <TITLE> element that names the application the user is 
logging in to. If the login failure page does not contain the same <TITLE> element, you can use the 
<TITLE> element to identity the login page. Suppose that this is true and the login page contains the 
following string: 


<TITLE>Novell WebAccess</TITLE> 


You would add this string as the value in the text box for the Page Matching Criteria option. 
Remember that white space is significant when white space is entered to the left of the value in the 
text box. To have Access Gateway ignore white space, left-justify the value in the text box, or to 
ensure the correct amount of white space, copy and paste the HTML text directly from the source 
code of the Web page. 


Now you need to uniquely identify the login failure page. If this page does not have a <TITLE> 
element, look at the strings near the top of the page. Suppose the page contains the following string: 


"Please log in again. You might have typed your name or password incorrectly." 


Because the login page does not contain this string, you can use this string to identify the login failure 
page. You would add the following string as the value in the text box for the Page Matching Criteria 
option for the login failure Form Fill policy. 


Please log in again. 


To have Access Gateway ignore white space, left-justify the value in the text box, or to ensure the 
correct amount of white space, copy and paste the HTML text directly from the source code of the 
Web page. 


Using Form Name Criteria 


After identifying the page, Access Gateway needs to identify the form on the page. If there is only one 
form on the HTML page, Access Gateway can easily identify the form. If the form has a name or an ID 
attribute, you can use the value of the attribute to identify the form. If the form does not’ have either of 
these attributes, you can use the Number option with a value of 1. The first form Access Gateway 
finds on the page matches. 


When multiple forms exist on the same HTML page, the easiest and fastest matching method is to 
give each form a unique name or unique ID on the HTML page. If the forms have the same name or 
ID, you need to use the Number option, and the order in which they appear on the page determines 
their number. 


The value O for the Number option has special meaning. You use this value when you want the Form 
Fill policy to fill in values for all forms on the page. Sometimes a page has multiple forms, but all forms 
on the page must be filled in before the page can be submitted. For example, one form might contains 
user information and another form contain user preferences. If both of these forms need to be filled in 
before the user can log in, then you can use the Number option set to 0, and the Fill Options section 
of the policy can contain fields for both forms, in the order in which they appear on the page. 
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Including JavaScript in a Form Fill Policy 
The following figure illustrates a simple form: 


Figure 8-27 Form Login Page 


Login Page 


E T 
Title: 

Password: 

LDAP SERVER: 


The source code for this simple form reveals that it includes JavaScript functions: 


<html><head><title>Login Page</title></head><body> 
<hi align="center">Login Page</h1> 
<script language="JavaScript"> 
function setCookie(){ 
document .cookie="myCookieName=myCookieValue"; 
} 
function validate(){ 
if(document.mylogin.title.ldap.length == 0){ 
alert("You must provide the title for the user!"); 
return false; 


} 
return true; 
} 
</script> 
<form name="jscript" action="viewInfo.php" method="post" onload="setCookie()"> 
<center> 
<table border="1" cellpadding="4" cellspacing="4"> 
<tbody><tr> 


<td>Username: </td> 
<td><input name="username" size="30" type="text"></td> 
</tr> 


<tr> 

<td>Title:</td> 

<td><input name="title" size="30" type="text"></td> 
</tr> 

<tr> 

<td>Password:</td> 

<td><input name="password" size="30" type="text"></td> 
</tr> 


<tr> 

<td>LDAP SERVER:</td> 
<td><input name="1dap" size="30" type="text"></td> 
</tr> 
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<tr> 

<td colspan="2" align="center"> 

<input value="Login" onclick="return validate();" type="submit"> 
</td> 


</tr> 
</tbody></table> 
</center> 
</form> 


<script language="JavaScript"> 
function doCookie(){ 
document .cookie="myCookieName=myCookieValue"; 


} 


return true; 


} 


</script> 


</body></htm1> 


The significant code snippets for determining whether to include JavaScript commands in the Form 
Fill policy are displayed in bold. The <script> elements are in bold because you need to be aware of 
all the JavaScript on the HTML page. Whether all the functions in the JavaScript need to be included 
in the policy is usually determined by trial and error. There are some clues you can use to determine 
the requirements: 


¢ If a function is called within the form, you must include it in the Form Fill policy. The above form 
calls two JavaScript functions, setCookie() and validate(). 


¢ If a function is not called by the form, you probably do not need to include it. The above form has 
one JavaScript function that falls within this category, doCookie. You can probably leave out 
these types of functions, but only trial and error can determine whether that is true. 


For this form, select the Auto Submit option and the Enable JavaScript Handling option. If you 
wanted to test whether the doCookie( ) function was needed, you would specify the following in the 
Functions to Keep text box: 


function setCookie( ) 
function validate() 


Each function needs to be placed on a separate line. This feature does a string compare, so the string 
after the function key word must match exactly a string in the JavaScript. 


Form Fill Character Sets (UTF-8) 


Access Manager supports only UTF-8 encoding (UCS Transformation Format 8) and ISO 8859-1. 
Otherwise, Form Fill translations to the secret data store cannot be guaranteed. 


Creating a Form Fill Policy 


1 Examine the source code for the HTML form and determine what data the form requires and 
where that data is stored (LDAP attributes, Liberty User Profile attributes, shared secrets, 
credential profiles, etc.) 


Ideally, the form must be its own HTML page, and the page must be as small as possible. Form 
Fill must parse the entire file and assemble the body in contiguous memory before the first byte 
of the form is displayed to the user. For a large file, this can take enough time that your users 
might think the system has a problem. 
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If it isn’t possible to have the form on its own HTML page, ensure that the form is easily 
identifiable on the page. For example, give the form a name or use CGI data (the text that the 
follows the question mark in the URL) to identify the page and form. 


In Administration Console Dashboard, click Policies > Policies. 

Select the policy container, then click New. 

Specify a name for the policy, select Access Gateway: Form Fill as its Type, then click OK. 
Fill in the following fields: 


Description: (Optional) Describe the purpose of this policy. Because Form Fill policies are 
customized to match the content of a specific HTML page, you might want to include the name of 
the page as part of the description. 


Priority: Determines the order in which a rule is applied in the policy, when the policy has 
multiple rules. Form Fill does not use this field. 


In the Actions section, click New and select Form Fill. 


7 Inthe Form Selection section, specify how Access Gateway can identify the form on the page. 


Select one or more of the following methods. Be specific and use as few of the methods as 
possible. For information about how to use these options effectively, see “Creating a Form 
Matching Rule” on page 837. 


Form Name: Identities the form on the HTML page. Select one of the following: 


+ Form Name: If the <form> element on your HTML page specifies a name attribute, select 
Form Name and specify the value of the name attribute in the text box. For example, 
suppose your form contains the following: 


<form name="mylogin" action="validatepassword.php" method="post" 
id="formi"> 


For this form, you would specify mylogin in the text box. 


+ Form Number: Access Gateway numbers forms sequentially from the top of the HTML 
page. If your page has multiple forms, you can use Form Number option and specify the 
form’s sequential location in the text box. 


+ Form ID: If the <form> element on your HTML page specifies an id attribute, select Form ID 
and specify the value of the id attribute in the text box. 


For example, if your form contains the following: 


<form name="mylogin" action="validatepassword.php" method="post" 
id="formi"> 


For this form, you would specify form1 in the text box. 
For more information, see “Using Form Name Criteria” on page 839. 


CGI Matching Criteria: Allows Access Gateway to evaluate the query string in the URL (the 
portion after the question mark) to differentiate pages that have the same URL. Consider the 
following URL: 


http://webaccess.novell.com/servlet/webacc?Action=User .login 
For this URL, enter the following string in the text box for CG! Matching Criteria: 
Action=User .login 


If possible, copy the text from the form and paste it into the CGI Matching Criteria text box. 
For more information, see “Using CGI Matching Criteria” on page 838. 
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Page Matching Criteria: Causes Access Gateway to search the HTML page for the specified 
text. If the specified text is found on the page, the page is a match for the policy. If it isn’t found, 
the page is not a match for the policy and the policy is not applied. For example, suppose your 
HTML page has the following string within the <FORM> element: 


<title>Form Fill Test Page</title> 


If you enter this string in the Page Matching Criteria box, Access Gateway searches the form for 
this string. If it finds the string, it knows it has a match. 


White space is significant. If the text in the text box is left-justified, the text can be found 
anywhere on the HTML page. If the text contains leading white space, such as ten spaces, the 
text must be found with ten leading spaces. If possible, copy the text as it appears on the form 
and paste it into Page Matching Criteria text box. 


The more specific your information is, the faster Access Gateway can match the form. Parsing 
page matching criteria is a very intensive process. If possible, use the URL path specified for the 
protected resource or CGI Matching Criteria to identity the form.For more information, see 
“Using Page Matching Criteria” on page 838. 


In the Fill Options section, create an entry for all the input fields and select options in the form. 
For each input field or select option, you need to specify the following information: 


Input Field Name: Specifies the name of the field or option. This is the name attribute or the ID 
attribute of the element on the form. 


NOTE: If both name and ID attributes are available, always specify the name attribute in Input 
Field Name. If you specify the ID attribute, form fill does not work. 


If only the ID attribute is available, the form gets filled with values, but auto submit does not work. 


Input Field Type: Specifies the type attribute for the input field or select option in the form. 
Select one of the following data types for the field: 


¢ Text: Indicates that the field is a text field on the form. 

+ Password: Indicates that the field is a password field on the form. 

+ Checkbox: Indicates that the field is a check box on the form. 

+ Radio Button: Indicates that the field is a radio button on the form. 

¢ Select: Indicates that the field is a select option on the form. 

+ Hidden: Indicates that the field is an input field, but that this field is hidden from the user. 


+ Not Specified: Indicates that the field is an input field, but the data type is not specified in 
the form. 


Input Field Value: Specify the value for the field. You must specify the data type, then enter the 
value. Select one of the following data types: 


+ Credential Profile: Specifies that the value must be retrieved from the credentials the user 
specified during authentication. If you have created a custom contract that uses credentials 
other than the ones listed below, do not use the Credential Profile as an input value. 


+ LDAP Credentials: If you prompt the user for a username and password, select this 
option, then either LDAP User Name (the cn of the user) or LDAP User DN (the fully 
distinguished name of the user). Your web server requirements determine which one 
you use. 


The default contracts assign the cn attribute to the Credential Profile. If your user store 
is an Active Directory server, the SAMAccountName attribute is used for the username 
and stored in the cn field of the LDAP Credential Profile. 
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+ X509 Credentials: If you prompt the user for a certificate, select this option, then 
select one of the following option depending on your web server requirements. 
— X509 Public Certificate Subject: Specifies that the subject field from the 
certificate must be the value, which can match the DN of the user, depending 
upon who issued the certificate. 


— X509 Public Certificate Issuer: Specifies that the issuer field from the certificate 
must be the value, which is the name of the certificate authority (CA) that issued 
the certificate. 


— X509 Public Certificate: Specifies that the entire certificate must be the value. 


— X509 Serial Number: Specifies that the certificate serial number must be the 
value. 


¢ SAML Credential: Injects the SAML assertion as the value of the field when SAML is 
used for authentication. This value is usually used for the user’s password. 


+ LDAP Attribute: Indicates that the value must be retrieved from the specified LDAP 


attribute. If the attribute you require does not appear in the list, click New LDAP Attribute to 
add the attribute. 


The Refresh Data Every option allows you to determine when to send a query to the LDAP 
server to verify the current value of the attribute. Because querying the LDAP server slows 
down the processing of a policy, LDAP attribute values are normally cached for the user 
session. 


Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. 


Liberty User Profile: Indicates that the input field contains a Liberty User Profile attribute. 
In the value field, select the attribute. The attribute you select must be mapped to an LDAP 
attribute, and Access Gateway retrieves its value from the LDAP directory. 


Shared Secret: Indicates that the input field contains a user-entered value that is to be 
stored in the specified shared secret store. 


You can create your own value. Click New Shared Secret, specify a display name for the 
store, and Access Manager creates the store. Select the store, click New Shared Secret 
Entry, specify a name for the attribute, then click OK. The store can contain one name/value 
pair or a collection of name/value pairs. For more information, see Section 8.5.4, “Creating 
and Managing Shared Secrets,” on page 853. 


NOTE: To store user-entered value in Shared Secret, ensure that you have specified the 
name attribute in Input Field Name. The ID attribute does not work with Shared Secret. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the secret. Because querying slows down the processing of a policy, secret 
values are normally cached for the user session. 


Change the value of this option from session to a more frequent interval only on those 
secrets that are critical to the security of your system or to the design of your work flow. You 
can select to cache the value for the session, for the request, or for a time interval varying 
from 5 seconds to 60 minutes. 


Virtual Attribute: Indicates that the value must be retrieved from the specified virtual 
attribute. 


The Refresh Data Every option allows you to determine when to send a query to verify the 
current value of the virtual attribute. Because querying slows down the processing of a 
policy, the virtual attribute values are normally cached for the user session. 
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Change the value of this option from session to a more frequent interval only on those 
attributes that are critical to the security of your system or to the design of your work flow. 
You can select to cache the value for the session, for the request, or for a time interval 
varying from 5 seconds to 60 minutes. For more information, see “Using the Refresh Data 
Option” on page 811. 


String Constant: Indicates that the input field contains a static value. In the text box, 
specify the value for the string constant. 


Data Extension: (Conditional) If you have installed a data extension for Form Fill policies, 
injects the value that the extension retrieves. For more information about creating a data 
extension, see NetIQ Access Manager Developer Tools and Examples (https:// 
www.netiq.com/documentation/access-manager-43-developer-documentation/). 


NOTE: To improve the policy's performance, configure the LDAP Attributes, Credential 
Profile, Liberty User Profile, and Shared Secret attributes to be sent with authentication. For 
more information, see “Configuring the Attributes Sent with Authentication” on page 188. 


Data Conversion: Specify whether the case of the value entered by the user must be 
converted. Select one of the following options: 


+ 


+ 


+ 


None: Indicates that no conversion must be performed on the value. 
To Upper Case: Indicates that the value must be converted to uppercase. 
To Lower Case: Indicates that the value must be converted to lowercase. 


LDAP DN to NDAP Partial Dot Notation: Converts the LDAP DN (which uses typed 
comma notation) to eDirectory ™ typeless dot notation. 


cn=jsmith, ou=Sales, o=novell to jsmith.sales.novell 


LDAP DN to NDAP Leading Partial Dot Notation: Converts the LDAP DN to eDirectory 
typeless leading dot notation. 


cn=jsmith, ou=Sales, o=novell to .jsmith.sales.novell 


LDAP DN to NDAP Fully Qualified Partial Dot Notation: Converts the LDAP DN to 
eDirectory typed dot notation. 


cn=jsmith, ou=Sales, o=novell to cn=jsmith.ou=Sales.o=novell 


NDAP Fully Qualified Leading Dot Notation: Indicates eDirectory typed leading dot 
notation. 


.cn=jsmith.ou=Sales.o=novell 


Shared Secret Type: This option allows you to choose how the value you specified in the 
HTML form must be stored in the shared secret store. 


+ 


None: When you select this default option, the value that you specified in the HTML form 
will be stored and retrieved from the shared secret store on subsequent login. 


Remember: This option allows you to only store the value that you specified in the HTML 
form to the shared secret store. 


Fill: This option allows you to only retrieve the value from the shared secret store. 
Example 8-3 Configuring a Form Fill Policy to Change Password Using Different Shared Secret Types 


For example, if you want to change password on a HTML form, the form will have Old 
Password, New Password, and Confirm Password fields. While configuring the Form Fill 
policy, on the password change page, select the shared secret type as Fill for the Old 


Access Manager Policies 845 


846 


Password field. For the New Password and Confirm Password fields select shared secret 
type as Remember. All the three input field names must point to the same shared secret 
entry. 


When you access the password change page, the old password will be auto filled. The New 
Password and Confirm Password fields will be blank. Enter the New Password and 
Confirm Password fields and submit the page. The Old Password will be replaced with the 
New Password in the shared secret entry. 


9 In the Submit Options section, specify how you want the information in the form submitted to the 


web server. (The HTML form page determines whether the post method or the get method is 
used for the submission.) Select one or more of the following options: 


Auto Submit: Indicates that you want the form submitted to the web server without having the 
user confirm the submission by clicking a Submit button. If this option is not selected, Form Fill 
can fill in the data, but the user must click the Submit button before the data is sent to the web 
server. When the form is not auto submitted, all the JavaScript on the form is executed. 


If you select Auto Submit, you can select one or more of the following options: 


+ Debug Mode: Allows you to verify that the information in the filled-in form is valid before it is 
posted to the web server. You can right-click and view the source that is being submitted to 
the web server. If it is correct, click Submit to send it to the web server. 


This is a troubleshooting option. We recommend that you use it when creating a new Form 
Fill policy, and that you remove it when you have determined that the policy is behaving as 
expected. 


+ Mask Data: Replaces text input field values (username, password, etc.) with nov-ss-ff- 
masked instead of the value specified by the value parameter when the form is sent to the 
browser. Access Gateway replaces these masked values with the real values when Access 
Gateway submits the form to the web server. The user’s browser never sees the actual 
values for these fields. 


+ Detect Loop: In some scenarios, Form Fill processor tries to auto submit the form and 
every time login fails, the form fill request goes into infinite loop. The Login Failure policy 
cannot handle the following scenarios: 


+ When a web server returns the same login page to Access Gateway after login failure. 


+ When a web server uses URL redirection or forwarding method to redirect a user to the 
same login page after login failure. 


If you have selected Auto Submit, you can select the Detect Loop option. This option allows 
you to detect the loop and auto submit stops. Access Manager will now ask you to fill the 
form in an interactive mode. 

This is achieved by creating a cookie in the browser, which will calculate the number of 
times the same form is posted to Access Gateway in a given period of time. These values 
are set to 3 submits in 6 seconds. 


Limitations: 
+ Use these options only when the Login Failure policy cannot detect or handle looping. 


+ When web server returns a different login form depending on a query-string or CGI 
portion of the URL, these options may not work as expected. 


Insert Text in Header: If this option is selected, you can use the Text to Insert option to specify 
text to add to the header. Use this option to insert static values into the form. 


Enable JavaScript Handling: Retains JavaScript from the original page if you have also 
selected the Auto Submit option. For a new Form Fill policy, you must also select the Debug 
Mode option so you can verify that you have included all the functions and statements that need 
to be executed in the policy. 
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Use the following fields to specify how you want the JavaScript handled: 


+ Functions to Keep: Specifies the functions you want executed from the JavaScript on the 


original page. By default, no functions on the page are executed. In the text box, use the 


following format: 
function setCookie() 


where function is a key word, followed by a space, and then the name of the function. 


Each function must be entered on a separate line, but you need only one function per script 
block. Everything must match exactly (name, capitalization, white space.) If you include the 
parentheses after the function name (setCookie()), they must exactly match the white space 


in the JavaScript. If possible, copy the function from the HTML page. 


+ Statements to Execute on Submit: Specifies the functions you want executed just before 
the form is posted. Copy the JavaScript statement from the HTML page or add a JavaScript 
statement that you want called that is not on the HTML page. This allows you to modify the 


behavior of the form when you can’t modify the form. 


If the text box is empty, the JavaScript function specified in the submit field of the HTML 
page executes before the form is posted. 


For more information, see “Including JavaScript in a Form Fill Policy” on page 840. 


In the Error Handling section, specify how you want errors handled. 


Redirect to URL: When an LDAP or NSS error occurs, the user is redirected to the URL you 


specify in the text box. This is optional and allows you to customize the error handling process. If 


you do not customize it, a standard error page is displayed. 
Click OK, then click Apply Changes. 


12 Continue with “Creating a Login Failure Policy” on page 847 or “Assigning a Form Fill Policy to a 


Protected Resource” on page 135. 


Creating a Login Failure Policy 


The Login Failure policy can be part of the same policy as the Form Fill policy, if both share the same 
URL. In this case, the Form Login Failure policy must be the first action in the policy, and the Form Fill 
policy must be the second action in the policy. This causes a login failure to execute the policy that 

clears the stored data and the Form Fill policy to prompt the user for new data. 


If the user is redirected to a different page when login fails, it is best to create a separate policy for 


that page, create a protected resource that includes just that page, and assign your Form Login 
Failure policy to that resource. 


To create a Login Failure policy: 
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In Administration Console Dashboard, click Policies > Policies. 

Select the policy container, then click New. 

Specify a name for the policy, select Access Gateway: Form Fill as its Type, then click OK. 
In the Actions section, click New > Form Login Failure. 


In the Form Selection section, identify the form. This section uses the same criteria for 
identifying a form as the Form Fill policy. For more information, see Step 7 on page 842 and 
“Creating a Form Matching Rule” on page 837. 


In the Login Failure Processing section, define the actions you want executed when a user fails 


to log in. Fill in the following fields: 
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Redirect to URL: When a user’s login attempt fails, use this option with its text box to specify 
the URL you want the user redirected to. This is optional and allows you to customize what 
happens on login failures. 


Clear Shared Secret Data Values From Policy: Select this field to delete the user’s stored 
data for a Form Fill policy. If the user has the ability (and perhaps the requirement) to periodically 
change his or her password or any other information about the form, you need to select this field. 
Otherwise, the wrong data can be stored for the user, and Access Gateway has no way of 
updating the information. 


From the list of Form Fill policies, select the policy whose stored values must be cleared with this 
Login Failure policy. 


7 Click OK > Apply Changes. 
8 Continue with “Assigning a Form Fill Policy to a Protected Resource” on page 135. 


Creating an Inject JavaScript Policy 


The Inject JavaScript policy adds the configured JavaScript to a protected resource page, when used 
in the interactive mode. You can create a standalone Inject JavaScript policy. You can also use this 
policy with the Form Fill policy. When you use the Form Fill policy with this one, configure the actions 
in the following sequence: 


1. Form Login Failure policy 

2. Form Fill policy 

3. Inject JavaScript policy 
When the Inject JavaScript policy is configured along with the Form Fill policy, ensure that Auto 
Submit is not enabled for the Form Fill policy. In the Configure Javascripts section, select the option 


where you want to insert JavaScript in the HTML page. The following are examples based on the 
option you have selected. 


In the head block 
Selecting this option inserts the following JavaScript in the header: 


<html> 

<head> 

<script language="JavaScript"> 
alert("Head"); 

</script> 


At the beginning of the body block 
Selecting this option inserts the following JavaScript just after the <body> tag. 


<title> Test Java Script</title> 
</head> 

<body> 

<script language="JavaScript"> 
alert("Begin Body"); 

</script> 


At the end of the body block 


Selecting this option inserts the following JavaScript just before the </body> tag. 
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BODY starts. <br> 

Inject Java Script. <br> 

BODY ends. <br> 

<script language="JavaScript"> 
alert("End Body"); 

</script> 

</body> 

</html> 


To create an Inject JavaScript policy: 
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In Administration Console Dashboard, click Policies > Policies. 

Select the policy container, then click New. 

Specify a name for the policy, select Access Gateway: Form Fill as its Type, then click OK. 
In the Actions section, click New > Inject JavaScript. 


In the Form Selection section, select the criteria. If you are creating a standalone Inject 
JavaScript policy, specify the criteria. For more information, see “Using CGI Matching Criteria” 
on page 838 and “Using Page Matching Criteria” on page 838. When you use the Inject 
JavaScript policy with the Form Fill policy, it uses the same criteria as that of the Form Fill policy. 


NOTE: If you do not specify a criteria in the Form Selection section, the Inject JavaScript policy 
is applied to all protected resource pages. 


Click OK > Apply Changes. 


7 Continue with “Assigning a Form Fill Policy to a Protected Resource” on page 135. 


Sample Inject JavaScript Policy 


The script in this example assumes that the contract timeout is five minutes. After four minutes, the 
user gets a popup message (timeout.html) with an option to refresh the page. If the user clicks on the 
option, the session is extended. If the user closes the popup or does not respond to the message, the 
system executes AGLogout and the session gets terminated. 


Perform the following steps: 


1 


Configure a Form Fill policy to insert Java Script into the head block of an HTML page. 
1a Go to Policies > New. 

1b Specify a name for the policy and select the type as Access Gateway: Form Fill. 
1c Inthe Actions section, click New and then select Inject JavaScript. 

1d Define a CGI matching Criteria or Page Matching Criteria. 

1e Under the Configure Javascript section, select In Head Block. 

1f Click Configure JavaScript and copy the following script: 
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<script language="JavaScript"> 
var X; 
var timerID ; 


function timeoutClock( ) 


if(x==60) // 60 seconds is the session time left when the session expire 
warning message appears. 

{ 

newwindow = 

window.open('timeout.html', 'towindow', 'toolbar=no, menubar=no, resizable=no, 
scrollbars=no, status=no, location=no, width=300, height=200'); 


if (x==0) 

window. location.href = 'https://www.ag1.com:443/AGLogout' // AGLogout link. 
} 

X=x-1; 


var t=setTimeout(function() {timeoutClock()} ,1000); 


} 


function resetClock( ) 


clearTimeout(timerID); 
x = 300; //5 Minutes. This is the contact timeout defined. 
timeoutClock(); 


} 


</script> 


In this script, set the value of x inside the function resetClock() according to the contract 
time out. In the example, x is set 300 that is equivalent to five minutes. Also, modify the 
following link in the script based on your configuration. This is a simple AGLogout link. 


window. location.href = 'https://www.agi.com:443/AGLogout ' 


1g Click OK > Apply Changes. 
2 Assign the policy to a protected resource. 
For more information, see “Assigning a Form Fill Policy to a Protected Resource” on page 135. 


3 Ensure to call the resetClock() function in the body tag of the HTML page (<body 
onload=resetClock();>). This initializes the counter to 300 every time the page is loaded. 
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4 Create a timeout .html page, which contains warning message for the user that the session is 
going to end soon. The content of timeout .html can be as follows: 


<script type="text/javascript"> 
var howLong = 60000; 
function closeMe() 


{ 


var t = setTimeout(function() {self.close()},howLong); 


} 


function closeCurrentWindow() 


{ 


window.close(); 


} 

</script> 

Click <a href="javascript :window.opener.location.href = 

window. opener. location.href;window.close()";>[here]</a>to refresh now. 
<br>Else you will be logged out in 60 seconds 

<body onload=closeMe(); 

Timeout 

</body> 


8.5.3.6 Troubleshooting a Form Fill Policy 


When a new Form Fill policy is not behaving as expected, use the following tips to discover the 
cause: 


¢ Select the Debug Mode option. This option prepares the form for submission, but does 
not’submit the form until you click the Submit button. This allows you to view the source, and 
determine if the policy is generating the required data. 


+ Ensure that all input fields have valid names, that the fields are being filled in the correct order, 
and that any JavaScript commands have been entered correctly. 


¢ Enable Form Fill logging. Form Fill is a function of both the proxy service and the Embedded 
Service Provider. The Embedded Service Provider logs the evaluation of the policy, and the 
proxy logs the process of gathering the data. To enable the Embedded Service Provider tracing, 
see Section 21.6, “Turning on Logging for Policy Evaluation,” on page 1062. To enable Access 
Gateway log entries for Form Fill policies, see “Enabling Form Fill Logging” on page 1287. 


Check for the following problems with the source content of the Form Fill page: 


¢ “Valid HTML Structure” on page 851 
+ “The Option Element Does Not Contain a Value Attribute” on page 852 
+ “The Form Element Does Not Contain a Method Attribute” on page 852 


Valid HTML Structure 


The Form Fill process aborts if the page does not contain valid HTML structure. The page must 
contain the <htm1></htm1> tags, and the form must contain the <form></form> tags. If these tags 
are missing, you must correct the source page on the web server. If this is not possible, you can 
create a rewriter policy to add the tags. 


+ To add the <html> tag, have the rewriter policy search for the <body> tag, and replace it with 
<html><body>. 
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+ To add the </html> tag, have the rewriter policy search for the </body> tag, and replace it with 
</body></html1>. 


+ Use similar entries to add the <form></form> tags. You'll need to discover which tag or phrase 
starts and stops the form. 


Configure your rewriter policy so that it runs before the default rewriter policy. For more information 
about rewriter policies, see Section 3.8.5, “Configuring HTML Rewriting,” on page 139. 


The Option Element Does Not Contain a Value Attribute 


If an <option> element does not contain a value attribute, Form Fill cannot fill the value. For 
example: 


<form action="Select.htm"> 
<select name="top2"> 
<option>Bob</option> 
<option>Alice</option> 
</select> 
</form> 


If your form contains <option> elements similar to these, they need to rewritten to contain a value 
attribute. For example: 


<form action="select.htm"> 
<select name="top2"> 
<option value="name1">Bob</option> 
<option value="name2">Alice</option> 
</select> 
</form> 


If possible, change the source page on the web server to add the value attribute to the <option> 
elements. If this is not possible, you can use a rewriter policy to add the value attribute. 


+ For the Bob option, have the rewriter policy search for <option>Bob and replace it with <option 
value="name1">Bob. 


+ For the Alice option, have the rewriter policy search for <option>Alice and replace it with 
<option value="namei">Alice. 


Configure your rewriter policy so that it runs before the default rewriter policy. For more information 
about rewriter policies, see Section 3.8.5, “Configuring HTML Rewriting,” on page 139. 


The Form Element Does Not Contain a Method Attribute 


If the <form> element does not contain a method attribute, Form Fill does not run an Auto Post. For 
example, the following form cannot use an Auto Post. 


<form name="loginForm"> 


To enable Form Fill so that it can run an Auto Post, you need to add a method attribute to the <form> 
element. For example: 


<form method="get" action="index.htm" name="loginForm"> 


If possible, change the source page on the web server to add the method attribute to the <form> 
element. If this is not possible, you can use a rewriter policy to add the method attribute. 


+ Search for <form 


+ Replace this string with <form method="get" action="index.htm" 
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Configure your rewriter policy so that it runs before the default rewriter policy. For more information 
about rewriter policies, see Section 3.8.5, “Configuring HTML Rewriting,” on page 139. 


8.5.4 Creating and Managing Shared Secrets 


A shared secret is an object that holds name and value pairs for Form Fill and Identity Injection 
policies. 


+ If your HTML form prompts the user for more than credential information, you need to create a 
shared secret to store the values. 


+ If your web server requires some name/value pairs to be injected and these are not available 
from the HTTP request, you need to create a shared secret to store these name/value pairs so 
that they can be injected into the header before it is sent to the web server. 


Access Manager supports the creation and use of secrets from the following locations: 


¢ In the local configuration store 
¢ In eDirectory user stores that are running Novell SecretStore 
¢ In a user store that has been configured with a custom attribute for secrets 


NOTE: Before using Access Manager to store and encrypt secrets, ensure that you choose your 
Preferred Encryption Method and change the default Encryption Password Hash Key value. If either 
of these options is changed after any secrets are stored, Access Manager will not be able to retrieve 
the secrets. 


For more information about configuring Access Manager to store secrets, see “Configuring a User 
Store for Secrets” on page 364. 


This section describes the following topics: 
¢ Section 8.5.4.1, “Naming Conventions for Shared Secrets,” on page 853 


¢ Section 8.5.4.2, “Creating a Shared Secret Independent of a Policy,” on page 854 
¢ Section 8.5.4.3, “Modifying and Deleting a Shared Secret,” on page 855 


8.5.4.1 Naming Conventions for Shared Secrets 


The policy engine allows you to create shared secrets and name the attributes for the store as you 
are creating an Identity Injection or Form Fill policy. When you create the shared secret, we 
recommend that you name the shared secret after the application for which you are creating the 
policy. Each value requires a name, and we recommend that you use the same name for the value 
name as the Input Field Name on a Form Fill policy or for the header name on an Identity Injection 
policy. For example if your e-mail application requires the e-mail address for the name on the login 
form, you could set up the following Shared Secret values: 


Input Field Name Input Field Value Shared Secret Name Entry Name 


emailaddress Shared Secret emailapp emailaddress 
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Your applications, how you use them, and your personal preferences determine whether you create 
one shared secret and use it for all your applications or whether you create a shared secret for each 
application. 


+ Ifthe applications use some of the same secrets, you can use the same shared secret for these 
applications. In this case, give the shared secret a name that reflects all of the applications using 
it. 

¢ If an application does not use the same secrets as another application and you want the freedom 


to remove the application and its secrets without affecting other applications, you must create a 
separate shared secret for this application. 


¢ If you are using Novell SecretStore, the secret names specified in your Access Manager policies 
need to match the names you have already configured. 


A local shared secret store does not contain any name/value pairs until you configure a Form Fill 
policy to add name/value pairs or enable the Allow End Users to See Credential Profile option. This 
option allows the username and password to be stored in the local secret store. To set this option, 
click Devices > Identity Servers > Edit > Liberty > Web Service Providers > Credential Profile. 


NOTE: You can create/edit/delete the values of a shared secret in the following scenarios: 


+ When you use a Form Fill policy. 


+ When you login to Identity Server and use the default landing page. Click on Profile > My Profile 
> Credentials > Credential List. This will be allowed only after enabling the Allow End Users to 
See Credential Profile as mentioned above. 


+ When you use other NetIQ products such as Identity Manager and Secure Login. This can be 
used if you are using external eDirectory secret store. 


¢ The Identity Injection policy can use the shared secrets, but will not allow to create/edit/delete 
the values of shared secrets. 


8.5.4.2 Creating a Shared Secret Independent of a Policy 
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You can create a shared secret as part of the process of creating a Form Fill or Identity Injection 
policy. You can also create a shared secret independent of a policy: 


1 In Administration Console Dashboard, click Devices > Identity Servers, then click Shared 
Settings > Custom Attributes. 


2 To create a new shared secret, click New in the Shared Secret Names section, and fill in the 
following fields: 


Secret Name: Specify a display name for the shared secret. 

Secret Entry Name. Specify an attribute name for a value you want to store. 
3 Click OK. 

Identity Server creates and encrypts the object. 


4 To create additional attributes to store values, click the secret name, click New, specify a name, 
then click OK. 


5 Click OK. 
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8.5.4.3 Modifying and Deleting a Shared Secret 


Before deleting a shared secret, you need to delete the policies that are using the shared secret or 
modify the policies to use a different shared secret. For information about deleting policies, see 
“Deleting Policies” on page 712. 


Both Form Fill and Identity Injection policies can use shared secrets. The following instructions 
explain how to modify an Identity Injection policy to use a new shared secret and then how to delete 
the old shared secret. 

1 In Administration Console Dashboard, click Policies > Policies > [Name of Policy] > [Rule]. 


2 Select the Value field that uses the shared secret you want to delete. Click its name, then click 
New Shared Secret. 


3 Specify the name for a new shared secret, then click OK. 


4 Click the name of the shared secret, select the new shared secret store, then click New Shared 
Secret Entry. 


Specify the attribute name for this shared secret entry, then click OK. 

Modify any other Value fields to use the new shared secret. Create new attributes as needed. 
To save the modifications to the policy, click OK twice, then Apply Changes. 

To delete the old shared secret, click Identity Servers > Shared Settings > Custom Attributes. 
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Select the name of the old shared secret and the attributes, then click Delete. 


8.5.5 Importing and Exporting Form Fill Policies 


You can import and export the Form Fill policies to run them in other Access Manager configurations 
and to analyze the policy. The policy is exported as a text file with XML tags. We do not recommend 
editing the exported file with a text editor. Any changes you want to make to a policy ought to be done 
through Administration Console. 


To export a Form Fill policy: 


1 In Administration Console Dashboard, click Policies > Policies. 
2 Select a Form Fill policy, then click Export. 
3 (Optional) Modify the name suggested for the file. 
4 Click OK. 
5 Using the features of your browser, specify where the file is be copied. 
To import a policy: 
1 Ensure that any referenced shared secret stores have been created. See Section 8.5.4, 
“Creating and Managing Shared Secrets,” on page 853. 


2 If the policy uses LDAP or Liberty Profile attributes, ensure that Identity Server has been 
configured for these same attributes. 


In Administration Console Dashboard, click Policies > Policies. 
Click Import, then browse to the location of the file. 

Click OK. 

When the policy appears in the list, click Apply Changes. 
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Configuring a Form Fill Policy for Forms With Scripts 


The Form Fill policy created for Access Gateway works well with forms that contain a Submit button 
whose onclick action submits the form data to the web server without executing any JavaScript or 

VBScript. However, when HTML forms contain complicated JavaScript or VBScript, Form Fill for that 
form fails. 


For example, single sign-on by using the Form Fill policy to fill and autosubmit a form fails if the 
Submit button or the login button requires execution of a JavaScript function before submitting the 
form data to the web server. 


The following sections explain why Form Fill fails with the Form Fill policy when the HTML form 
contains complicated JavaScript. This section also describes the procedure to configure a Form Fill 
policy for such forms. 


¢ Section 8.5.6.1, “Why Does Form Fill Fail with the Default Policy?,” on page 856 
¢ Section 8.5.6.2, “Understanding How a Form Is Submitted,” on page 858 
¢ Section 8.5.6.3, “Creating a Form Fill Policy for Autosubmission,” on page 859 


¢ Section 8.5.6.4, “Configuring the Advanced Options for Autosubmission,” on page 859 


Why Does Form Fill Fail with the Default Policy? 


The following section explains the process that takes place when a client requests a form that is 
configured with the Form Fill policy as described in Chapter 8.5, “Form Fill Policies,” on page 831. 


Figure 8-28 Sample Login Form with JavaScript 


Login: testuser1 | 


Password: ([eeccccecece | 


Language. ©" x 


When Access Gateway is configured with the default Form Fill policy, it adds the following function to 
the Login page received from the web server. The bold text indicates where JavaScript is called. 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 
<!--Generated by Apache Software Foundation (Xalan XSLTC)--> 
<html class="detail/detail"> 


<head> 
<META http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
<script type="text/JavaScript"> 
/*SET up global vars*/ 
//all the variable declaration 


<script type="text/JavaScript"> function dvdRegisterSelect ( ) 
{ } </script> 


<title>Login Page</title> 
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<body id="tpz_body" style="width:99%; "onload="tpzOnLoad('login.prompt.g'); 
window. status='login.prompt.g'; ContextMenu.setup({'showForms':true}); 
ContextMenu.attach('detail/detail', 'cwc_optionsMenu_detail')" 
onfocus="window. status='login.prompt.g'" > 


<script type="text/JavaScript"> var arReenable = new Array(); 
function enableAll() {return reenableControls(arReenab1le) ; } </script> 
<script type="text/JavaScript"> //all the variable declaration 
function verify( f, bSubmitToSelf ){ return verifyFields 
(bSubmitToSelf,"\n");} </script> 
<div> 
<a title="Login" class="tabSelected">Login</a> 
</div> 


<formname="topaz" id="topaz"method="post" action="detail.do" 
onsubmit="enableAll();return verify(this, true) ;"> 

<input type="hidden" name="focus" id="focus" value="var/user.id"> 

<input type="hidden" name="focusContents" id="focusContents" VALUE="testuser1i" 
<input type="hidden" name="focusId" id="focusId" VALUE="X2" > 

<input type="hidden" name="formname" id="formname" VALUE="login.prompt.g"> 
<input type="hidden" id="clientWidth" name="clientWidth" VALUE="1473" > 


<script type="text/javascript"> function 
printThisView( ){tpzPrintDetail( );} </script> 


<input type="text" id="X2" name="var/user.id" dvdVar="" 
onclick="handleOnClick(this,event);" VALUE="testuser1i" scripttype="text"> 
<input type="password" id="X5" name="var/old.password" dvdVar="" 
onclick="handleOnClick(this, 

event);" " VALUE="novell081" > 


<input type="button" name="0" id="X8" ButtonID="0" title="Login Page" value="Login" 


onclick="tpzDrillTable('', 'Login', '0','listdetail')" > 

<input type="button" name="3" id="X9" ButtonID="3" title="Exit Login Page" 
value="Cancel" onclick="tpzDrillTable('', 'Cancel', '3','listdetail')" > 
</form> 


<script language="JavaScript"> <!-- function 
LAGSubmitForm( ) { document. forms[0].submit(); 
} LAGSubmitForm(); //--> </script> 
</body> 
</html> 


In the above code, the LAGSubmitForm( ) function calls the default submit action of the form, which 

uses a POST request to send the data to the web server. But the submit action for the sample login 
form requires a JavaScript function to be executed. This function in turn submits the form data to the 
web server. However, because the JavaScript is not executed by the default Form Fill policy, posting 


of the form data fails: 


row=&__x=&thread=0&event=0&transaction=0&type=detail&focus=var%2Fuser .id&focusCont 
ents=testuser1&focusId=x2&focusReadOnly=&star t=&count=&more=&tablename=&window=&cl 
ose=&_blankFields=&_uncheckedBoxes=&formchanged=&formname=Login. prompt .g&_multiSel 
ection=&_multiSelection_tableId=&clientWidth=1473&var%2Fuser .id=testuseri&var%2Fol 


d.password=novell081&var%2FL . language=en&0=Login&3=Cancel 
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Meanwhile, the browser expects to receive the following POST request and does not autosubmit the 
form: 


row=&__x=&thread=0&event=0&transaction=0&type=detail&focus=var%2Fuser .id&focusCont 
ents=testuser1&focusId=xX2&focusReadOnly=null&start=&count=&mor e=&tablename=&window 
=&close=&_blankFields=&_uncheckedBoxes=&formchanged=&formname=login. prompt .g&_mult 
iSelection=&_multiSelection_tableId=&clientWidth=1217&a&var%2Fuser .id=testuser1l&var% 
2Fold.password=novell081&var%2FL.language=en 


Note the difference in POST requests sent to the browser. The first POST request has 
&0=Login&3=Cancel appended, which causes the login to fail. 


For the browser to send the proper POST data, Access Gateway must add the following JavaScript 
statement to the Statements to execute section: 


tpzDrillTable('', 'Login', '@', 'listdetail'); 


Understanding How a Form Is Submitted 


For Access Gateway Appliance, you can configure the Form Fill policy to submit the form in the 
following ways: 


¢ Manual Submit: When a form is configured for manual submission, all the fields configured in 
the Form Fill policy are automatically filled by Access Gateway for the user. The user must then 
manually click the Submit button in the form to submit the form to the web server protected by 
Access Gateway. 


+ Autosubmit: When Autosubmit is configured, the actual form is processed in such a way that all 
additional scripts not required to submit the form data to the web server are removed. A 
temporary form is created on runtime with necessary form data in hidden format and with an 
additional LAGSubmitForm() function as follows: 


function LAGSubmitForm() 
{ 


executeJavaScript(); 


LAGSubmitForm(); 


In this example, executeJavaScript() is the function that executes the JavaScript or the 
VBScript statements configured in the Statements to execute section. If statements to be 
executed are present, you can also find the function definition for executeJavaScript() as 
follows: 


executeJavaScript() 


document .forms[0].submit(); 


} 


In this example, form[@] is the single form in the HTML page and submit is the default action 
associated with the submit or login button of the form that automatically submits the form to the 
web server. This approach works for forms where the default action of the Submit button is to 
submit a POST request for the form data. 


+ Autosubmit with Masking: When Autosubmit with masking is enabled for a form, the form data 
is submitted automatically to the web server, but the data sent to the Web browser over the 
network is masked for additional security. 
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¢ Submitting with the help of advanced options: If your form requires the execution of 
JavaScript when the form is submitted, you cannot use the Autosubmit options.This also means 
that single sign-on is disabled. 


To create a policy that allows autosubmitting for this type of form, you need to create the policy 
as described in “Creating a Form Fill Policy for Autosubmission” on page 859 and create two 
advanced options as described in “Configuring the Advanced Options for Autosubmission” on 
page 859. 


8.5.6.3 Creating a Form Fill Policy for Autosubmission 


In Administration Console Dashboard, click Policies > Policies. 

Select the policy container, then click New. 

Specify a display name for the policy and select Access Gateway: Form Fill for its type. 
(Optional) Specify a description for the Form Fill policy. 

In the Actions section, click New, then select Form Fill. 

In the Form Selection section, select Form Name and specify topaz in the text box. 

In the Fill Options section, specify all the input fields and select the options that you want. 
In the Submit Options section, select Auto Submit. 
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Select Enable JavaScript Handling. 
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Select Functions to Keep, then specify the JavaScript functions that need to be retained when 
the form is being automatically submitted. For the example form, specify the following functions: 


function dvdRegisterSelect() 
function enableAll() 
function verify(f, bSubmitToSelf ) 
function printThisView() 
function tpzDrillTable(a,b,c,d)() 
11 Click OK. 
12 Select Statements to Execute and specify the form action that needs to be performed when the 
form is submitted. For the sample form, specify the following statement: 


function executeJavaScript() 


tpzDrillTable('', 'Login', '@', 'listdetail'); 
} 


executeJavaScript(); 


You must perform this step to execute the functions configured in the Functions to keep section 
because Access Gateway does not process HTML to include the LAGSubmitForm() function. 


13 Click OK. 
14 On the Policies page, click Apply Changes. 


8.5.6.4 Configuring the Advanced Options for Autosubmission 


When HTML forms contain complex JavaScript or VBScript, you must enable the following two 
advanced options: 


+ #NAGGlobalOptions InPlaceSilent=on: This enables single sign-on to certain websites that 
require the login page to remain as is without any modifications to its structure. This option is 
equivalent to .enableInPlaceSilentFill in the 3.1 SP4 Access Gateway Appliance. 
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8.6.2 


+ #NAGGlobalOptions InPlaceSilentPolicyDoesSubmit=on: This option enables form fill in 
HTML pages with complex JavaScript or VBScripts. This option is equivalent to 
.enableInPlaceSilentFillNew in the 3.1 SP4 Access Gateway Appliance. 


To enable these options: 


1 Inthe Administration Console, click Access Gateways > Edit > Advanced Options. 


2 Add the following in the Advanced Options list: 
NAGGlobalOptions InPlaceSilent=on 
NAGGlobalOptions InPlaceSilentPolicyDoesSubmit=on 


3 Click OK. 


External Attribute Source Policies 


You can use Access Manager as an identity provider for third-party service providers. Some of these 
service providers require attributes that are not part of the user store where the user is authenticated. 
The External Attribute Source policy allows you to retrieve attributes from the external sources. 


You can configure this policy with rules to retrieve the attributes. A rule can contain all the conditions 
available for a policy. To enable this policy, you need to write a data extension class or provide a 
string constant value. The data extension class can be configured with constant and dynamic 
properties like any other policies. 


For information about the structure and template of a data extension class and example code, see the 
“The Policy Extension API” in the NetIQ Access Manager 4.3 Developer Guide. 


Enabling External Attributes Policy 


An External Attributes policy must be enabled and configured before users can use the policy for 
fetching the attributes from external sources. 


For assigning a policy to users, you must enable it for Identity Server configuration. 


1 Click Devices > Identity Servers > Servers > Edit > External Attributes. 

2 Select the check box against the policy name and click Enable. 

3 To disable the policy, select the check box against the policy name and click Disable. 

4 To create a new policy, click Manage Policies. 

5 After enabling or disabling policies, update Identity Server configuration on the Servers tab. 


Creating an External Attribute Source Policy 


1 Click Policies > Policies > New. 


2 Specify a name for the policy, select Identity Server: External Attribute Source for the type of 
policy, then click OK. 


3 Specify the following details: 
Description: (Optional) Specify the purpose of this policy. 


Priority: Specify the sequence in which a rule is applied in the policy, when the policy has 
multiple rules. The highest priority is 1 and the lowest priority is 10. 


4 Inthe Actions section, click New, then select Fetch Attributes. 
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5 Specify the following details: 
External Attribute Name: Specify the name of the attribute to be obtained through this policy. 
Value: Specify either String Constant or Data Extension for the attribute value. 


If you select String Constant, provide the value in the text box. The policy returns the string 
constant. 


If you select Data Extension, select the extension file from the list. The policy returns the 
attributes based on the logic defined in the class. 


For more information about policy extension, see Section 8.1.6, “Adding Policy Extensions,” on 
page 716. 


6 Click OK twice, then click Apply Changes. 


7 After creating an External Attribute Source policy, create a shared secret. This shared secret is 
used in configuring other policies or can be used by Identity Servers in their attribute sets to 
retrieve attributes from external sources. 


For more information, see “Creating Shared Secret Names” on page 84. 


External Attribute Source Policy Examples 


You can use an External Attribute Source policy to retrieve attributes from external sources. You can 
create shared secrets from this policy. This shared secret then can be used in configuring other 
policies or can be used by Identity Servers in their attribute sets to retrieve attributes from external 
sources. 


An External Attribute Source policy must be enabled and configured before using the policy for 
retrieving the attributes from external sources. 


For more information about how to create an External Attribute Source policy, see Section 8.6.2, 
“Creating an External Attribute Source Policy,” on page 860. 


This section describe the usages of the External Attribute Source policy with the help of the following 
scenarios: 


¢ “Scenario 1” on page 861 


¢ “Scenario 2” on page 863 


For information about sample codes for these examples, see Access Manager SDK Sample Code 
(https://www.netig.com/documentation/access-manager-43-developer-documentation/samplecodes/ 
main.html). 


Scenario 1 


e Health is a Web portal for doctors. e_Health uses Med_Association as an external identity provider 
to verify whether the user is a doctor and obtain the user's professional code and specialization. 
Med_Association retrieves these details with the help of Access Manager Identity Server. 


Med_Association completes the following steps: 


1. Write an External Attribute data extension class and use the required attribute to retrieve the 
professional code and specialization of user. 


For more information about data extension class, see Section 8.1.6, “Adding Policy Extensions,” 
on page 716. 


Access Manager Policies 861 


For more information about data extension example code, see The Policy Extension API in the 
NetIQ Access Manager 4.3 Developer Guide. 


2. Create an External Attribute Source policy for the data extension. 


For more information about how to import the data extension class and configure the External 
Attribute Source policy in Identity Server, see Chapter 8.6, “External Attribute Source Policies,’ 
on page 860. 


3. Define a shared secret for the professional code and specialization. 

For more information, see Section 3.5.4, “Adding Custom Attributes,” on page 84. 
4. Configure this shared secret for a service provider to be sent with authentication. 

For more information, see “Configuring the Attributes Sent with Authentication” on page 188. 
5. The retrieved details that are professional code and specialization are sent to e_Health. 


The following diagram illustrates this scenario: 


Med_Association External Attribute 


Source for example, JDBC source 
Web Service and so on. 


(Ta) 


7—_o—-y 


Identity Server LDAP Directory 


—Q-——- 
a pa-an 


Browser e_ Health 


Workflow: 


1. User requests for access to e-Health through browser. 


2. e Health redirects the user’s browser to Access Manager Identity Server at Med_Association for 
authentication. 


3. User logs in with providing credentials. User is authenticated with LDAP. 
4. On the successful authentication, Identity Server sends the assertion to e_Health. 
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5. e Health verifies the assertion with Med_Association by using the back channel communication. 


6. After verification, Access Manager Identity Server retrieves the attributes (professional code and 
specialization) from external sources (for example, database) by using the External Attribute 
Source policy. 


7. Identity Server returns the response containing professional code and specialization in a shared 
secret attribute. If the user is not a doctor, external source returns null values in the shared 
secret attribute in the response. 


e Health grants access to the user if it receives valid values for the attributes in the 
authentication response else it denies Access. 


8.6.3.2 Scenario 2 


Company XYZ is a customer of Access Manger. The employees of this company get authenticated to 
Identity Server. Each employee's mail attribute is retrieved from the user store. XYZ wants only user 
name part of the email address to be displayed on the Home page after authentication. This can be 
achieved by using the External Attribute Source policy. 


XYZ completes the following steps: 


1. Write an External Attribute data extension class and use the mail attribute as the parameter to 
the class. 


For more information about data extension class, see Section 8.1.6, “Adding Policy Extensions,” 
on page 716. 


2. Inthe data extension class, read the email address and parse the name identifier in it and return 
as an attribute. For more information about data extension example code and example code for 
this scenario, see The Policy Extension API in the NetIQ Access Manager 4.3 Developer Guide 
guide. 


3. Define a shared secret for the name field of the email address. 
For more information, see Section 3.5.4, “Adding Custom Attributes,” on page 84. 
4. Create an External Attribute Source policy for the data extension. 


For more information about how to import the data extension class and configure the External 
Attribute Source policy in Identity Server, see Section 8.6.2, “Creating an External Attribute 
Source Policy,” on page 860. 


5. Create an Identity Injection policy. 


For more information, see Chapter 8.4, “Identity Injection Policies,” on page 810 and 
Section 8.4.4, “Configuring a Custom Header Policy,” on page 818. 
6. Identity Server sends the user ID part of email address to Access Gateway. 


In turn, Access Gateway or service provider sends this attribute to the configured web server. 
For example, John is an employee of XYZ. He provides his email address, john@mail- 
domain.com, as his user name. After authentication, only John will be displayed on the Home 
page. 
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The following diagram illustrates this scenario: 


5 


External Attribute 
Source for example, JDBC source 
Web Service and so on. 


Identity Provider 
LDAP Directory 


an 


ho AoA 


Web Server 
Browser Access Gateway (with basic authentication) 


Workflow: 


1. User (through the browser) is requesting for a resource. Access Gateway determines whether it 
is a protected resource and redirects the request to Identity Server for authentication. Identity 
Server authenticates with the LDAP servers and provides the assertion details to Access 
Gateway. In turn, Access Gateway verifies the assertion details. 


2. The Home page in the resource is configured to display the user ID that has to be retrieved from 
Identity Server. 


3. Identity Server determines whether the attributes can be retrieved from the external source. 
Identity Server will send the required details to the external source (in this example, an email 
address). 


. The external source returns the data. In this example, user ID part of the email address. 
. Identity Server sends the data that it has obtained from the external source to Access Gateway. 
. Access Gateway sends the data to the web server. 


N DO on f 


. The web server returns the resource. 
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8.7.1.1 


Risk-based Policies 


This section includes the following topics: 


+ 


+ 


+ 


+ 


+ 


+ 


Section 8.7.1, “Configuring Risk-based Authentication,” on page 865 

Section 8.7.2, “Configuring User History,” on page 874 

Section 8.7.3, “Configuring Geolocation Profiling,” on page 876 

Section 8.7.4, “Configuring NAT Settings,” on page 877 

Section 8.7.5, “Configuring an Authorization Policy to Protect a Resource,” on page 877 
Section 8.7.6, “Risk-Based Authentication: Sample Configuration,” on page 878 


For more information about risk-based authentication, see “Risk-based Authentication” on page 658. 


Configuring Risk-based Authentication 


Configuring risk-based authentication involves the following steps: 


1. Create a risk policy. For more information, see “Configuring a Risk Policy” on page 865. 


. Create a method for the risk-based authentication class. For more information, see “Configuring 


a Method for an Authentication Class” on page 869. 


. Create a contract for the risk-based authentication class. For more information, see “Configuring 


a Contract for an Authentication Class” on page 869. 


You must consider the following points while configuring the risk-based authentication: 


A rule must be included in a risk policy. A rule can exist in multiple risk policies. 
A risk-based authentication class maps to only one risk policy and vice versa. 


If a rule condition is not met, the score associated with that rule is added to the risk score. If the 
rule condition is met, the specified action is executed. 


The risk level is determined based on the total risk score, that is the sum of the scores of all rule 
conditions that are not met. 


If a rule is configured to allow or deny access and exit the policy when a condition is met, the risk 
score is zero as other rules in the group are not evaluated. 


Configuring a Risk Policy 


Before creating a risk-based policy, determine the following to understand the criteria for defining a 


The application or resource you want to protect. 

The parameters you want to assess during a login attempt. 
The risk score for each parameter. 

The risk levels for risk scores. 

The action for the risk levels. 

If you want to record the details of risk assessment. 


If you want to store history details from the risk assessment in MySQL, MicroSoft SQL Server, or 
Oracle database. 
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O If you want to perform profiling on user login events based on the geolocation of the user. 


O If you want to assess the risk before a user attempts to login. 
Configuring a risk policy includes the following three parts: 


1. Adding a Risk Policy 
2. Configuring Policy Rules 
3. Configuring Risk Levels 


Adding a Risk Policy 


1 Click Policies > Risk-based Policies > Risk Policy. 
If there is no risk policy configured, clicking Risk Configuration opens the Overview page. 
2 Click the Create Risk Policy icon. 


NOTE: To create an identical copy of any existing risk policy: 
1. Click Policies > Risk-based Policies > Risk Policy. 


2. Locate the policy you want to clone and click the Clone Risk Policy icon. All rules and risk 
levels configured for the existing policy are copied to the new policy. 


3. Specify a name for the new policy and assign a cluster and an authentication class. 


3 Under Add Risk Policy, specify the following details: 
Risk Policy Name: Specify a name for the policy. 
Policy Description: Describe the purpose of this policy. 


Assign Policy To: Select Identity Server cluster and then select an authentication class. You 
can select the class from the list of existing classes or you can create a new class. 


NOTE: If you select an existing class, settings of the selected class are overwritten with values 
of this policy. 


For creating a new class, perform the following steps: 


Configuring a Risk-based Authentication Class 
3a Select either of the following options: 
Create Risk-based Auth Class: 


Calculates the risk score after authentication. For more information, see “Risk 
Assessment and Risk Mitigation after Authenticating a Login Attempt’ on page 661. 
Create Risk-based Pre-Auth Class 


Calculates the risk score before authentication. For more information, see “Risk 
Assessment and Risk Mitigation before Authenticating a Login Attempt” on page 660. 


NOTE: To modify an existing authentication class go to Identity Server > cluster > Edit > 
Local > Classes. 

3b Specify a name for the class. 

3c Select Record User History to record the user’s login details. 


Before enabling this option, ensure that you have enabled recording user history in Policies 
> Risk Configuration > User History and configured a database. For more information, see 
“History:” on page 665. 
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NOTE: The Record User History option is available only for Risk-based Auth Class. 


Select Use Cumulative Risk Score to add current risk score of the session to this 
evaluation. 


If you select this option, ensure that you have defined appropriate risk levels in this class to 
accommodate the cumulative value. For more information, see “Cumulative Scoring:” on 
page 666. 


To send the user name, risk score, and risk level of a specific login attempt to an external 
REST interface, click Score Sharing URLs and specify the URL of the interface. The 
external REST interface uses this score information to perform additional actions on the 
user’s identity. 


(Optional) Specify the REST endpoint authentication credential. Whenever the risk score is 
sent to the REST endpoint, the endpoint sends these credentials as a basic authentication 
header. If the REST endpoint is protected by using basic authentication, then this credential 
is used. 


If Reduce Score is enabled, the reduced risk score is sent to the REST endpoint for a 
successful additional authentication. 


After enabling Score Sharing URLs, you must enable the identified risk scores for sharing. 


You can enable two Score Sharing URLs. If the REST endpoint is down, a warning 
message is logged in the log file (Linux: catalina. out; Windows: stdout . 10g). If the REST 
endpoint is down during risk score sharing, the risk is not cached and will not be shared 
later. 


NOTE: The Score Sharing URLs option is available only for Risk-based Auth Class. 


4 Continue with Configuring Policy Rules. 


Configuring Policy Rules 


You can select a rule from the existing list or create a new rule and then assign it to the risk policy. 
You can assign multiple rules to a policy. The rules are executed in the top to bottom sequence. You 
can drag and drop to change the priority and sequence of rules. Rules for which action is defined as 
Allow Access, Deny Access, or Exit with Risk Level as specified risk level are executed 
as specified in the rule irrespective of the risk score accumulated for other rules that previously failed. 


For each rule you want to add to a policy, you must perform the following steps: 


1 To create a new rule, perform the following actions: 


Click Actions > Create Rule. 

Specify a rule name. 

Select a rule definition. For details, see Step 2 in “Configuring Rules” on page 870. 
Click OK. 

Define actions for the rule. 
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Condition Action 


If rule condition is met Select any of the following options: 


+ Proceed to Next Rule: The next rule in the execution sequence is 
executed. 


+ Allow Access and Exit Policy: No other rules of this policy is 
executed and the user will get access to the resource. 


+ Deny Access and Exit Policy: No other rules of this policy is 
executed and the user will be denied access. 


+ Exit with Risk Level as: Select a risk level. You can also create a 
risk level and then assign it to the rule. For information about 
creating a new risk level, see Configuring Risk Levels. No other 
rules in this policy are executed. The action specified for that risk 
level is executed. 


If rule condition is not Specify the risk score that will be stored when the rule evaluation fails. 
met, add risk score 


NOTE: You can also create a rule here Policies > Risk-based Policies > Rules > New. See 
“Configuring Rules” on page 870. 


2 To select a rule from the existing list, perform the following actions: 
2a Under Policy Rules, click Actions > Add Existing Rule. 
2b In Risk Rule, select the rule you want to add from the list. 
2c Define actions for the rule. For details, see Step 1e on page 867. 


NOTE: To validate the rule configuration and view the result when a condition is met, click 
Actions > Toggle Validate. For more information, see “Understanding How to Use the 
Validate Tool to Emulate Total Risk Score and Risk Levels” on page 680. 


3 Continue with Configuring Risk Levels. 
Configuring Risk Levels 


1 Under Risk Levels, click Actions > Add Risk Level. 
2 Specify the following details: 
Ħ Risk Level: Select a risk level to associate with the risk score. If you select Other, specify a 


name to identify the custom risk level. 


Risk Score: Specify a risk score to be associated with the risk level. The risk score indicates 
a value that is stored in the database after rule evaluation fails. 


Action: Select an action for this risk score. 


If you select Additional Authentication under Action, you can either select a class ora 
method to configure the step-up authentication. Typically, the step up to a method is used 
when branding, overwriting of users, or a change of userstore is required. If the userstore of 
the Additional Authentication is same as the risk-based authentication class and no 
additional branding is needed, then use a class. 


Reduce Score: After a successful additional authentication, you can configure to reduce the 
associated risk score. Specify the value that you want to reduce from the risk score in this 
field. For more information, see “Risk Score Reduction after a Successful Additional 
Authentication:” on page 666. 
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¢ Share Score: Select this option if you want to send the risk score of this risk level to the URL 
specified in Score Sharing URLs in the associated authentication class. You can share risk 
scores only for the risk levels configured for Risk-based Auth Class. 


This option is available only if at least one Share Score URLs is configured for the 
authentication class. 


3 Continue with “Configuring a Method for an Authentication Class” on page 869. 


8.7.1.2 Configuring a Method for an Authentication Class 


Click Local > Method > New to create a new method for the risk based authentication class. 
Specify a name to identify the method. 
Select the risk-based authentication class from Class. 
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Deselect Identifies User. 


NOTE: If the policy is using Risk-Based Pre-Auth Class, this options must be selected at least 
in one method of the contract. 


5 Select a user store from the list of Available User Stores. 


IMPORTANT: In a risk-based authentication class, properties configured for the risk-based 
authentication method are ignored. So, if you want to configure additional properties, add the 
property to the risk-based authentication class. 


6 Continue with “Configuring a Contract for an Authentication Class” on page 869. 


8.7.1.3 Configuring a Contract for an Authentication Class 


1 Click Local > Contract > New to create a new contract for the risk based authentication class. 
2 Specify a name to identify the contract. 


3 You can either use an existing authentication contract or create a new authentication contract. 
For example, for Risk-based Auth Class, you can add the default Name/Password — Form 
method as the first method and risk-based authentication method as the second method. For 
Risk-based Pre-Auth Class, the risk-based authentication method must be configured as the 
first method. 


4 Click Next to configure a card for the contract. For more information about configuring contracts, 
see Section 5.1.4, “Configuring Authentication Contracts,” on page 379. 


NOTE: If you want to use this contact in federation, ensure that you assign this contract to a 
protected resource. 
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8.7.1.4 Configuring Rules 


1 Click Policies > Risk-based Policies > Rules > New. 


2 Specify a name for the rule and select a rule type in Rule Definition based on your requirement 
and specify the details. 


Rule Type Procedure 


IP Address 1. To manually add IP addresses, select Manually enter the Datasource. You 
can specify a single IP address, IP address range, IP address subnet, or 
upload a text file containing IP addresses. To specify the IPv4 subnets, use the 
Classless Inter-Domain Routing (CIDR) notation. 


Click Add to List. 

Sample text format 

# Example IP List 

10.0.0.0 

172.16.0.0 

192.168.0.0 

Each entry in the text files must be on a separate line. 


2. To consider the list of IP addresses provided by an external provider or an 
internal web service, select Dynamically consume from the Datasource. 


a. Specify URL of the provider. 


b. In Connection Timeout, specify the time in second. After this specified 
time, an unresponsive connection is closed. For example, 5 seconds. 


c. In Refresh Interval, specify the time in second. The connection will be 
refreshed at the specified interval. For example once in 86400 seconds. 


The external provider provides the list of IP addresses in text or JSON formats. 
Sample text format 

# Example IP List 

10.0.0.0 

172.16.0.0 

192.168.0.0 

Sample JSON format 

["10.0.0.0","172.16.0.0","192.168.0.0"] 


3. Specify how the conditions for the rule must match. The available options are 
Is and Is Not. For more information about Is and Is Not conditions, see 
Table 5-6, “Risk-based Authentication Terms,” on page 668. 


4. To validate the user history recorded in the database, select Check user 
history. You can use this option only when Record user history is enabled in 
the User History tab. 


IMPORTANT: You cannot specify the IP subnet in the IPv6 format. Instead, 
you can use the IP range condition and define it in the IPv6 format. 
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Rule Type Procedure 


Cookie 1. Specify the name of the cookie. 


2. Specify the value of the cookie. The different search criteria that you can use 
are Is and Is Not. For more information about Is and Is Not condition, see 
Table 5-6, “Risk-based Authentication Terms,” on page 668. 


3. [Optional] If the cookie is not found, but you want to create a cookie after the 
user authenticates, select Create cookie if the user authenticates 
successfully. 


a. Specify the validity of the cookie in days. 
b. Specify the path for the cookie. 


IMPORTANT: A cookie is set only when the user is authenticated by 
using second-factor authentication. The cookie is not created if the risk is 
assessed to be low and the user authenticates by using primary 
authentication method. 


HTTP Header 1. Specify the HTTP header Name. 


2. Specify the HTTP header value that you want to search for an HTTP header 
that includes a specific value. For example, if you want to search for an HTTP 
header that includes the value NetIQ, you can use the search criterion Equals. 
Whereas, if you want to query for an HTTP header that does not include the 
value NetIQ, use Does Not Contain. 


User Profile 1. Select an LDAP attribute from the list. If you want to define a custom LDAP 
attribute, click New. 


2. Specify how the conditions for the rule must be matched. 


3. Specify the value of the attribute to be searched. For example, if you selected 
the LDAP attribute birthDate for rule creation, specify the birth date to be 
searched. 


User Last Login Specify the name of the last login cookie. 
Specify the path for the cookie. 
Specify the validity of the cookie in days. 


If you want the cookie to be secured by HTTPS, enable Secure Cookie. 
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Specify the number of days the cookie can be accessed from the same device 
or system. This value must be less than the value in Max Age. 


6. Specify the crypto key to encrypt the cookie. 


IMPORTANT: A User Last Login cookie is set only when the user is 
authenticated by using second-factor authentication. A User Last Login cookie 
is not created if the risk is assessed to be low and the user authenticates by 
using primary authentication method. 


User Time of 1. Select Is/Is not condition based on your requirements. This determines how 
Login the conditions for the rule must be matched. 


2. Specify the date and time of the user login. 


3. To validate the user history recorded in the database, select Check user 
history. To use this option, enable Record User History in the User History 
tab. 
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Rule Type 


Device 
Fingerprint 


Procedure 


1. Specify the validity of the fingerprint in number of days. 
2. Select any one of the following options under Store Fingerprint in: 
+ Browser: To store the fingerprint in the browser cache on the device. 


¢ Server: To store the fingerprint in the configured risk-database. You can 
use this option only in risk-based post-authentication scenarios. To store 
the fingerprint in risk-database, you must enable storing the user history 
in the User History tab. (Policies > Risk-based Policies > User History) 


NOTE: Storing a fingerprint in Built-in Data Store (Bundled eDirectory) 
is not supported. 


3. Specify the number of fingerprints you want to store per user. This option is 
applicable only when you select Server to store fingerprints. The permissible 
value is 1 to 5. 


4. Click Parameter Settings if you want to modify the default settings. For 
information about parameters, see Section 6.2, “Understanding Device 
Fingerprint Parameters,” on page 691. 


Device ID 


(Deprecated) 


In Access Manager 4.3, this rule has been replaced with the Device Fingerprint rule. 
If you have configured any Device ID rule in Access Manager 4.1 or 4.2, this rule will 
be listed as deprecated after upgrading to Access Manager 4.3. 


Geolocation 
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1. Specify the geolocation details. 


2. Select Is/ls not condition based on your requirements. This determines how 
the conditions for the rule are matched. 


3. To validate the user history recorded in the database, select Check user 
history. To use this option, select Record User History in the User History 
tab. 


Rule Type 


External 
Parameter 
Configuration 


Procedure 


1. Select Negate Result to reverse the result of the rule evaluation. For example, 
if you have defined this rule to get authentication details of a request using a 
specific IP address, you can use Negate Result to define the rule to not 
consider inputs originated from that IP address. 


2. Under External Parameter, add the following details for a parameter set: 
a. Name of the parameter. 
b. Specify the regular expression if required. 


For example, suppose an external source sends the following value for 
the Virtual IPv4 parameter: 


The Virtual IP address is 127.0.0.1 


To extract the IP address from this string, you can specify a regular 
expression as follows: 


(2: (2:25[0-5]|2[0-4] [0-9] | [01]?[0-9][9- 
9]?)\\. ){3}(?:25[0-5]|2[0-4] [0-9] | [01]?[0-9][0-9]?) 


This regular expression extracts the IP address 127.0.0.1 from the 
string and uses it for evaluating the configured condition. For more 
information about regular expression syntax, see the Javadoc for 
java.util.regex.Pattern. 


c. Select a relational or string operator to define a relationship between the 
parameter and parameter value. For example, whether a parameter must 
contain the specified parameter value or it must not be equal to the 
specified value. The available operators include contains, does not 
contain, is equal to, is equal to ignore case, is greater than, is 
greater than or equal to, is less than, is less than or equal to, in 
between, is not equal to, is not equal to ignore case. 


d. Specify a parameter value for evaluation. 


e. Click Add Parameter to add more parameters in this parameter set. You 
can define multiple parameters in a parameter set. 


3. (Conditional) Click Add Parameter Set to define additional parameter set. You 
can define multiple parameter sets. 


4. lf you have defined two or more parameter sets, specify how the conditions for 
the parameters must match. The available options are Or and And. For more 
information, see Combination Rule in Table 5-6, “Risk-based Authentication 
Terms,” on page 668. 


For an example about configuring external parameter, see “Using External 
Parameters in Risk Assessment:” on page 667. 


NOTE: To use this rule, you must create a custom class to retrieve details from an 
external provider. For more information, see “User Information Methods” and 
“Creating an Authentication Class” in the NetIQ Access Manager 4.3 Developer 
Guide. 
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Rule Type Procedure 


Custom Rule 1. Specify a fully qualified name of the custom class for which you want to create 
a custom rule. For example: com.Company.test.MyCustomclass. 


2. Select Check user history to check the user history details if the rule 
execution fails. 


3. Select Negate Result if you want to reverse the results of rule execution. For 
example: if you have defined a rule to track authentication attempts from a 
specific geolocation, you can use Negate Result to define a rule to allow 
authentication if the user logging in is not from that geolocation. 


4. Click Add Property to add custom properties and values. 


8.7.2 Configuring User History 


When you choose to record user history details for a risk policy that is linked to an authentication 
class, you get the flexibility to segregate the history details as per your requirement. 


Consider a situation where you have configured the following two risk policies: 


+ One risk policy assesses authentication requests from internal users in an organization. 
+ Another risk policy assesses authentication requests from users external to the organization. 


The following risk-rules support enabling user history: 


+ Custom Rule 

+ Device Fingerprint Rule 
¢ Geolocation Rule 

+ IP Address Rule 

+ User Time of Login Rule 


To record the history details for internal users only, enable the recording of user history at the risk- 
based authentication class that is used to authenticate the internal users. 


Recording the user history involves the following steps: 
1. Configuring an external database to log history records. For more information, see Section 5.5.9, 
“Configuring an External Database to Store User History,” on page 679. 
2. Enabling user history. For more information, see “Enabling User History” on page 874. 


3. Enabling user history while configuring a rule. For more information, see “Configuring Rules” on 
page 870. 


4. Configuring user history for a risk policy that is linked to an authentication class. For more 
information, see “Configuring a Risk-based Authentication Class” on page 866. 


8.7.2.1 Enabling User History 


1 Click Policies > Risk-based Policies > User History. 
2 Select Enable User History to save the user session details in the database. 


874 Access Manager Policies 


8.7.2.2 


3 Under History Settings, you can either specify the number of days of history to consider during 


the rule execution or select the option to consider all historical records. For example, if you 
specify 10, it indicates that the details of last 10 days must be considered during the rule 
execution. If you do not specify the number of days, all historical records are considered for the 
execution. 


NOTE: If you select Built-in Data Store (Bundled eDirectory) as History Data Store, specify the 
number of entries instead of the number of days. eDirectory supports recording history only up to 
5 entries. 


(Conditional) To store details in eDirectory, select Built-in Data Store (Bundled eDirectory). 


NOTE: In a production environment, it is strongly recommended that you do not use eDirectory 
as the data store. 


(Conditional) If you choose to save the session details in an external database, select External 
Database. 


5a Specify the name to identify the driver. 


5b Select the Database Driver. The driver path and dialect are displayed. You can change the 
driver and dialect details if required. 


5c Specify the Username and Password to access the database. 
5d Specify the URL to access the database. 


NOTE: To configure MySQL as the database, ensure that the database URL is specified as 
mysql://db_user:db_user@localhost/netig_risk?autoReconnect=true. 


For information about configuring an external databases, see Section 5.5.9, “Configuring an 
External Database to Store User History,” on page 679. 


Deleting Risk-based Authentication and Device Fingerprint Entries 
from the Database 


If you have enabled user history, details for all login attempts using a risk-policy or a device fingerprint 
policy are recorded in the database. This may result in huge data and occupy a large space. It is 
recommended to delete the entries periodically after you complete the analysis. 


+ 


+ 


+ 


“Deleting Entries from MS SQL Server” on page 875 
“Deleting Entries from MySQL Server” on page 876 


“Deleting Entries from Oracle Server” on page 876 


Deleting Entries from MS SQL Server 
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Go to Start > All Programs > Microsoft SQL Server 2016 > SQL Server Management Studio. 
Connect to the database engine. 

Expand Databases, you can see the netiq_risk database. 

Click New Query. 


To check the number of entries in the usrtransaction table, select the following command and 
click Execute. 


Select * from dbo.usrtransaction; 


To delete entries, select the following command and click Execute: 
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Delete from dbo.usrtransaction; 


NOTE: This command deletes all entries in the table. If you want to delete a specific range of 
entries, use the appropriate SQL command. 


7 Perform step 5 and 6 for the device fingerprint table (device_fingerprint) also. 


Deleting Entries from MySQL Server 
1 Connect to MySQL Server installed on Linux by using the MySQL client: 


mysql -u root -p password 

2 Connect to the use netiq_risk database. 
use netig_risk; 

3 List the tables. The usrtransaction table is listed in the list of tables. 
show tables; 

4 Delete entries. 


delete from usrtransaction; 


NOTE: This command deletes all entries in the table. If you want to delete a specific range of 
entries, use the appropriate SQL command. 


5 Perform step 4 for the device fingerprint table (device_fingerprint) also. 


Deleting Entries from Oracle Server 


Open Oracle SQL Developer. 

Right-click Connections and select New Connection. 

Connect to the database engine. 

Expand Connections, you can see the netiq_risk database under . 
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To check the number of entries in the usrtransaction table, select the following command and 
execute: 


Select * from usrtransaction; 
6 To delete entries, select the following command and execute: 


Delete from usrtransaction; 


NOTE: This command deletes all entries in the table. If you want to delete a specific range of 
entries, use the appropriate command. 


7 Perform step 5 and 6 for the device fingerprint table (device_fingerprint) also. 


8.7.3 Configuring Geolocation Profiling 


1 Click Policies > Risk-based Policies > Geolocation. 


2 Select Enable Location Profiling to fetch location data from a geolocation database. This helps 
to identify the location of the user based on the IP address details. 
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3 Select a Geolocation Provider. The available options are: 


Database Details 


Neustar Service + Specify the API Key and API Secret. 
+ Specify the Web Service URL. 


Custom Provider + Specify a name to identify the provider. 
+ Specify the fully qualified name of the JAVA class. 


+ Click Add Property to add properties to the custom class. 


8.7.4 Configuring NAT Settings 


8.7.9 


You can configure Identity Server to retrieve IP addresses in a NAT environment. 


1 Click Policies > Risk-based Policies > NAT Settings. 
2 Specify the name of the field to use for fetching the IP address of the client. 
3 Specify the regular expression to retrieve the client IP address from the HTTP header value. 


When you use the regular expression .* , the rule execution fails even if the client IP address 
exists in the list of multiple IP addresses. So, if you want to retrieve an IP address from a list of 
multiple IP addresses, modify the regular expression accordingly. 


For example: If you specify the regular expression as .*?(?=,), Identity Server considers the first 
IP address in the list to calculate risk.So, if the list of IP addresses are similar to 
10.20.20.1,10.30.30.1,10.40.40.1, the regular expression .*?(?=,) returns IP address 10.20.20.1. 


NOTE: if you have only one address, .* is sufficient. The approach described in step 3 is required for 
a list of addresses in the x-forwarded-for format. 


Configuring an Authorization Policy to Protect a Resource 


In an authorization policy, you can define a condition group that uses risk scores from Identity Server 
to protect a resource. 


Defining a Condition Group and Assigning Actions: 


Select Policies > Policies. 
Select the policy container and click New. 
Specify a name for the policy and select Access Gateway: Authorization for the type of policy. 
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From the Condition Group, select Risk Score. For more information about Comparison, Value, 
and Result on Condition Error, see Risk Score. 


5 Select an action. For more information about actions, see step 7 in Creating Access Gateway 
Authorization Policies. 
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8.7.6 Risk-Based Authentication: Sample Configuration 


This section explains the use cases and their configuration steps demonstrated in the Try Now option 
on the Risk Configuration > Overview interface. 


Let us assume a company named Company1 wants to control access to its resources. There are two 
users. One is a permanent employee of Company1 and another is a trainee at Company1. This 
configuration will refer the regular employee as Employee and the trainee as Trainee. 


Company1 wants to achieve the following actions: 
+ Scenario 1: Trainee or Employee is accessing the resource by using the internal network: Allow 
access. 
¢ Scenario 2: Trainee is accessing the resource by using the external network: Deny access. 


¢ Scenario 3: Risk associated with accessing the resource from an external network can depend 
various conditions. The following are the conditions with equal weightage: 


+ Employee’s request contains a cookie from the Intranet site or has a header from the Payroll 
site, indicating that Enployee was successfully logged into these resources earlier. 


+ Employee is logging in during normal work hours that is 9 am to 5 pm 


All conditions are evaluated. The risk decreases as the number of conditions met increases. The 
action performed depends on the risk score and associated risk level. 


The following diagram illustrates the rule execution logic of the demo risk policy: 
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P 
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Condition Condition 
Internal External Internal External External 
Network Network Network Network Network 
+ + 
Request contains a login time is in between 
valid known cookie or 9 am to 5 pm 
header 
Action Action 
Allow Deny Allow Consider the risk Consider the risk 
access access access score and score and 
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proceed to the 
next rule 


proceed to the 
next rule 


Action will be taken 
based on the total risk 
score and matching 
risk levels 


You can configure rules for these scenarios and arrange the rules in the order of priority on the UI. 
The rules are executed based on the priority from top to bottom. You can drag and drop rules on the 
UI to change their priority. 


In this sample, the following five rules are created and executed in the same sequence: 


Sequence of Rule Name Action 
Execution 
1 DemoRule_InternalNetwork: If Trainee or Employee is in the internal network, then 


allow access and exit the policy. 
If not, add risk score of 20 and proceed to the next rule. 


2 DemoRule_TraineeUser If Trainee is accessing from an external network, deny 
access and exit the policy. 


If Employee is accessing from an external network, add risk 
score of 20 and proceed to the next rule. 


3 DemoRule_Combo If Employee is accessing with a cookie from the payroll site 
or HTTP Header value contains loggedIn, proceed to the 
next rule with the total risk score accumulated due to the 
failure of the above three rules. 


For example, assume the risk score for each rule is 20. If 

the condition for this rule is met, then proceed to next rule 
with a risk score 60. If the condition for this rule is not met, 
then proceed to next rule with a risk score of 80. 


NOTE: To use this rule, you must set cookies or headers 
per domain with a path of /, so that Identity Server can 
receive them. 


4 DemoRule_TimeOfLogin If Employee is logging in using an external network and 
time is in between 9 AM to 5 PM, proceed to the next rule. 
The risk score will depend on whether the condition of the 
DemoRule_Combo was met. 


If the conditions of both DemoRule_Combo and 
DemoRule_TimeOfLogin rules fail, the total risk score will 
be 100 and access will be denied. 


The following steps have been performed to configure the demo risk policy for the identified 
scenarios: 
1 Go to Policies > Risk-based Policies > Risk Policy. 
2 Click the Create Risk Policy icon. 
3 Under Add Risk Policy, specify the following details: 
Risk Policy Name: Specify Demo_RiskPolicy. 
Policy Description: Specify the purpose of this policy. 
Assign Policy To: Select Identity Server cluster and then configure an authentication class. 
3a Select Create Risk-based Auth Class. 
3b Specify Class Name as Demo_RBAAuthClass. 
3c Click Save. 
4 Create the following rules: 
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Under Policy Rules, click Create Rule and specify the following values: 
4a DemoRule_InternalNetwork 
¢ Rule Name: DemoRule_InternalNetwork 
+ Rule Definitions: IP Address Rule 
+ Specify the IP address range as 121.1.1.1 -121.121.255.255 and click OK 
+ If rule condition is met, then: Allow Access and Exit Policy 
+ If rule condition is not met, add risk score: 25 
+ Click OK. 
4b DemoRule_TraineeUser 
¢ Rule Name: DemoRule_TraineeUser 
¢ Rule Definitions: User Profile 
¢ Select EmployeeType, Equals, and then specify Trainee. Click OK 
+ If rule condition is met, then: Deny Access and Exit Policy 
+ If rule condition is not met, add risk score: 25 
+ Click OK. 
4c DemoRule_Combo 
¢ Rule Name: DemoRule_Combo 
¢ Rule Definitions: 
Rule 1: Cookie Rule 
Cookie Name: IntranetCookie 
Cookie Value: is test 12 
Rule 2: HTTP Header Rule 
HTTP Header Name: PayrollAccessHeader 
HTTP Header Value: Contains loggedIn 


¢ Combination Rule Definition: In Condition Group, click Assign Rules and then select 
both rules. Select OR in Group Operator 


+ If rule condition is met, then: Proceed to Next Rule 
+ If rule condition is not met, add risk score: 25 
+ Click OK 
4d DemoRule_TimeOfLogin 
è Rule Name: DemoRule_TimeOfLogin 
¢ Rule Definitions: User Time of Login Rule 
User time of login: is 
Day: Monday to Friday 
Time: 9 AM to 5 PM 
+ Click OK 
+ If rule condition is met, then: Proceed to Next Rule. 
+ If rule condition is not met, add risk score: 25 
+ Click OK 
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5 Under Risk Levels, click Actions > Add Risk Level and create the following risk levels: 


+*+ Low 
Field Value 
Risk Score Less than 35 
Risk Level Low 
Action Allow Access 
+ Medium 
Field Value 
Risk Score Between 35 and 75 
Risk Level Medium 
Action Authenticate using Trust levels 
+ High 
Field Value 
Risk Score Greater than 75 
Risk Level High 
Action Deny Access 
6 Click OK. 


7 Create an authentication method. For more information, see “Configuring a Method for an 


Authentication Class” on page 869. 


8 Create a contract. For more information, see “Configuring a Contract for an Authentication 


Class” on page 869. 
9 Assign the contract to the protected resource. 
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9.1 


9.1.1 


High Availability and Fault Tolerance 


You can provide fault tolerance for the configuration store on Administration Console by installing 
secondary versions of the console. 

¢ Section 9.1, “Installing Secondary Versions of Administration Console,” on page 883 

¢ Section 9.2, “Configuration Tips for the L4 Switch,” on page 886 

¢ Section 9.3, “Setting up L4 Switch for IPv6 Support,” on page 891 

¢ Section 9.4, “Using a Software Load Balancer,” on page 895 


Installing Secondary Versions of Administration 
Console 


Administration Console contains an embedded version of eDirectory, which contains all configuration 
information of Access Manager. It also contains a server communications module, which is in 
constant communication with the Access Manager modules. If Administration Console goes down 
and you have not installed any secondary consoles, your Access Manager components also go down 
and your protected resources become unavailable. 


You can create fault tolerance by installing up to two secondary consoles. You must install at least 
one secondary console. 


¢ Section 9.1.1, “Prerequisites,” on page 883 


¢ Section 9.1.2, “Installing Second Console,” on page 884 


¢ Section 9.1.3, “Understanding How Consoles Interact with Each Other and with Access Manager 
Devices,” on page 885 


Prerequisites 


© Administration Consoles must have their time synchronized. You can ensure this by configuring 
the machines to use the same network time server for time synchronization. 


© Secondary consoles must be installed on the same operating system as the primary console. 
For example, if your primary console is installed on Windows, all secondary consoles must be 
installed on Windows. If your primary console is installed on Linux, all secondary consoles must 
be installed on Linux. 


O If you are going to install your clustered Identity Servers on the same machines as your primary 
and secondary consoles, Administration Consoles cannot be configured as a virtual group on an 
L4 switch. For more information, see “Managing Administration Consoles Installed on Clustered 
Identity Servers” on page 884. 
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9.1.1.1 Managing Administration Consoles Installed on Clustered Identity 
Servers 


You can install the primary Administration Console and Identity Server on the same machine, even 
when Identity Server is going to be assigned to a cluster of Identity Servers. You can install a 
secondary Administration Console on another member of Identity Server cluster. Administration 
Consoles cannot be configured as a virtual group on an L4 switch. The L4 switch interferes with the 
communication process between Administration Consoles and the Access Manager components. 
Each Access Manager component knows which Administration Console is its primary console and its 
secondary console and knows how to communicate directly with each console. The component, 
rather than an L4 switch, needs to make the decision on which console it needs to contact. 


However, traffic destined for a cluster of components (Identity Servers or Access Gateways) must 
pass through an L4. Figure 9-1 illustrates this configuration, showing Identity Servers on the same 
machine as Administration Consoles. 


Figure 9-1 Identity Server Clustering with a Secondary Administration Console 
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1. Install the primary Administration Console and an Identity Server on one machine by using 
Administration Console’s IP address when importing Identity Server component. 


2. Install the secondary Administration Console and a second Identity Server on another machine 
by using the primary Administration Console’s IP address when importing the second Identity 
Server. 


3. Specify the L4 VIP as the DNS for Identity Server cluster configurations that both Identity 
Servers use. (See “Configuring an Identity Server” on page 59.) 


9.1.2 Installing Second Console 


1 Insert the CD containing Administration Console software. 


Most of the installation process is the same for a secondary console as for a primary. For these 
basic instructions, see Installing the Administration Console in the NetIQ Access Manager 4.3 
Installation and Upgrade Guide. 


2 To install a secondary console, answer No to the following prompt: 
Is this the primary administration server in a failover group? 


3 When prompted, specify the IP address of the primary console. 
4 Continue with the installation process. 
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9.1.3 


9.1.3.1 


After installing a secondary console, you might need to wait from 30 to 60 minutes before using 
it. The components query the primary console hourly for information about available consoles, 
and they reject commands from a console that is not in their approved list. You can force 
components to recognize the secondary console by restarting the Integration Agent on each 
Identity Server and Access Gateway with the following command: 


/etc/init.d/novell-jcc restart 


Understanding How Consoles Interact with Each Other and 
with Access Manager Devices 


Primary and secondary consoles use eDirectory synchronization to keep their configuration 
databases current. 


WARNING: As long as the primary console is running, all configuration changes must be made at the 
primary console. If you make changes at both a primary console and a secondary console, browser 
caching can cause you to create an invalid configuration. 


Access Manager devices use the secondary console only when the primary console is down. 
Therefore, if a secondary console goes down while the primary console is running, devices are 
notified. But they continue to run by using the primary console for configuration information. The 
secondary console can be down for as long as required to fix the problem without affecting other 
Access Manager devices. 


When the primary console goes down, all of the devices discover this and switch to using the 
secondary console. This can take a few minutes, because each device has its own trigger for 
checking in with Administration Console. After the device has switched to using the secondary 
console, it continues to run just as it did when it was communicating with the primary console. When 
the primary console comes back online, all devices discover this and switch back to using the primary 
console. Again, this can take a few minutes. 


Not all tasks are available from the secondary console: 


¢ Section 9.1.3.1, “Tasks Requiring the Primary Console,” on page 885 
¢ Section 9.1.3.2, “Tasks Available from the Secondary Console,” on page 886 


Tasks Requiring the Primary Console 


The primary console must be used for the following tasks: 


New Device Installation: The primary console must be running when you install new devices such 
as another Access Gateway. 


Backup and Restore: Backup and restore must be run on the primary console. When the restore is 
completed, you must restart Tomcat on all secondary consoles. 


¢ Linux: Run the following command: 
/etc/init.d/novell-ac restart 
+ Windows: Run the following commands: 


net stop Tomcat7 
net start Tomcat7 
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9.1.3.2 


9.2 


9.2.1 


9.2.2 


For more information about backup and restore, see Chapter 28, “Back Up and Restore,” on 
page 1129. 


Tasks Available from the Secondary Console 


When the primary console goes down, the secondary console can be used for the following tasks: 


¢ Administrators can make configuration changes on a secondary console, and these changes are 
sent to Access Manager components. 


+ Access Manager components can use the secondary console to access their configuration 
information and to respond to configuration changes. When the primary console becomes 
functional, components revert to using the primary console, but they continue to accept 
commands from the secondary consoles. 


Configuration Tips for the L4 Switch 


When you use an L4 switch to cluster Identity Servers, Access Gateways, or both, you need to 
configure it and the DNS server for each cluster. You need to configure the DNS server to resolve the 
base URL of Identity Server configuration to Identity Server VIP on the L4 switch. You need to 
configure the DNS server to resolve the published DNS names of Access Gateway to Access 
Gateway VIPs on the L4 switch. 


In addition to this basic setup, consider the following: 


¢ Section 9.2.1, “Sticky Bit,” on page 886 

e Section 9.2.2, “Network Configuration Requirements,” on page 886 
¢ Section 9.2.3, “Health Checks,” on page 887 

¢ Section 9.2.4, “Real Server Settings Example,” on page 890 

¢ Section 9.2.5, “Virtual Server Settings Example,” on page 891 


Sticky Bit 


Each L4 switch has a slightly different method and terminology for the sticky bit or persistence bind. 
This bit allows a client that has established a session to be directed to the same Identity Server or 
Access Gateway for all requests sent during the session. This minimizes the need to forward session 
information between Access Gateways or between Identity Servers and thus maximizes 
performance. 


Network Configuration Requirements 


When you set up the L4 switch, the following configurations are required to route all Access Manager 
traffic through the L4 switch: 


Switches: When you install an L4 switch, you can plug the machines directly into the L4 switch or 
plug them into an inner switch that is plugged into the L4 switch. When you use inner switches with an 
L4 switch, you must use at least two inner switches: one for Identity Servers and one for Access 
Gateways. An Identity Server and an Access Gateway cannot share the same inner switch. Such a 
configuration causes communication problems because Access Gateway and Identity Server try to 
establish direct communication with each other rather than routing all traffic through the L4 switch. 
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Network Routing Requirements: You need to analyze your routing configuration. Identity Servers 
and Access Gateways must be connected to separate ports in the L4 switch. If there is a connection 
in your network that allows an Identity Server or an Access Gateway to communicate directly with a 
client without going through the L4 switch, Access Gateway and Identity Server try to establish direct 
communication with the client because networking protocols are configured to select the most direct 
route. Such a configuration causes communication problems because all traffic must be routed 
through the L4 switch. Figure 11-4 illustrates this problem. 


Figure 9-2 Network Configuration with a Potential Communication Problem 
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If your network allows for this type of communication, you need to block the communication channels 
illustrated with the dotted lines. 


Figure 11-5 shows each cluster type with its own L2 switch. An Access Gateway cluster and an 
Identity Server cluster cannot share the same L2 switch because they can see the MAC address for 
each other. Networking protocols are configured to use the most direct route for the communication, 
and the MAC address is more direct than going up to the L4 switch and back down. Such a 
configuration causes communication problems because all traffic between the clusters needs to be 
routed through the L4 switch. Using a separate L2 switch for each cluster type prevents them from 
gaining access to the MAC address and forces communication to take place through the L4 switch. 


9.2.3 Health Checks 


L4 switches use health checks to determine which cluster members are ready to receive requests 
and which cluster members are unhealthy and must not receive requests. You need to configure the 
L4 switch to monitor the heartbeat URL of Identity Servers and Access Gateways, so that the L4 
switch can use this information to update the health status of each cluster member. 


The procedure is slightly different for Identity Servers and Access Gateways: 


¢ Section 9.2.3.1, “Health Checks for Identity Server,” on page 888 
¢ Section 9.2.3.2, “Health Checks for Access Gateway,” on page 888 
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9.2.3.1 


9.2.3.2 


Health Checks for Identity Server 


Administration Console uses the heartbeat URL to display the health status of Identity Servers. 
Identity Server heartbeat is the DNS name of Identity Server plus the following path: 


/nidp/app/heartbeat 


L4 switches require you to use IP address rather than the DNS name. If the IP address of Identity 
Server is 10.10.16.50, and you have configured Identity Server for HTTPS, the heartbeat has the 
following URL: 


https://10.10.16.50:8443/nidp/app/heartbeat 


You need to configure the L4 switch to use this heartbeat to perform a health check. If you have 
configured SSL on Identity Servers and your L4 switch has the ability to do an SSL L7 health check, 
you can use HTTPS. The SSL L7 health check returns a value of 200 OK, indicating that everything 
is healthy; any other status code indicates an unhealthy state. 


For a Foundry switch, the L7 health check script string must look similar to the following when the 
hostname is nidp1 and the IP address is 10.10.16.50: 


healthck nidpissl tcp 
dest-ip 10.10.16.50 
port ssl 
protocol ssl 
protocol ssl url "GET /nidp/app/heartbeat HTTP/1.1\r\nHost: st160.lab.tst" 
protocol ssl status-code 200 200 
17-check 


If your switch does not support an SSL L7 health check, the HTTPS URL returns an error, usually a 
404 error. Because Identity Server heartbeat URL listens on both HTTPS and HTTP, you can use an 
HTTP URL for switches that do not support the SSL L7 health check. For example: 


http://10.10.16.50:8080/nidp/app/heartbeat 


An Alteon switch does not support the L7 health check, so the string for the health check must look 
similar to the following: 


open 8080, tcp 

send GET /nidp/app/heartbeat HTTP/1.1\r\nHOST:heartbeat.lab.tst \r\n\r\n 
expect HTTP/1.1 200 

close 


Health Checks for Access Gateway 


External communication to Access Gateway is typically configured to use HTTPS. In an HTTPS 
configuration, an L4 switch performs health checks of Access Gateways with the published DNS 
name of Access Gateway plus the following path: 


/nesp/app/heartbeat 


L4 switches require you to use IP address rather than the DNS name. If the IP address of Access 
Gateway is 10.10.16.172, and you have configured Access Gateway for HTTPS, the heartbeat has 
the following URL: 


https://10.10.16.172:443/nesp/app/heartbeat 


For an L4 switch to support an HTTPS query for the health of Access Gateway, the switch must 
support an L7 health check. For a Foundry switch, the L7 health check script string must look similar 
to the following when the hostname is ag1 and the IP address is 10.10.172. 
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healthck agissl tcp 
dest-ip 10.10.16.172 
port ssl 
protocol ssl 
protocol ssl url "GET /nesp/app/heartbeat HTTP/1.1\r\nHost: sti60.lab.tst" 
protocol ssl status-code 200 200 
17-check 


If your L4 switch does not support an SSL L7 health check, the HTTPS health check URL returns an 
error, usually a 404 error. To solve this problem, you can create a specialized reverse proxy that 

opens a non-SSL port for the heartbeat URL. The following instructions configure this reverse proxy 
to use port 81, because port 80 on the specified IP address is reserved for redirects to the SSL port. 


To create a reverse proxy for the health check: 
1 In Administration Console Dashboard, click Devices > Access Gateways > Edit > Reverse Proxy 
! Authentication. 


2 To create an additional reverse proxy service (such as heartbeat), click New, then specify a 
name. 


3 Change the Non-Secure Port to 81. 


Configure Access Gateway to listen on the same IP address as the service using port 443. For 
non-SSL, you must use port 81. Do not use port 80. 


For proper heartbeat information when there are multiple IP addresses configured in your 
Access Gateway, ensure that you configure the reverse proxy service created for the heartbeat 
URL to listen in the same IP address as the authenticating reverse proxy service. 


4 Click New to create the proxy service. 
5 Configure the following fields: 
Proxy Service Name: Specify a name that identifies the purpose of this proxy service. 


Published DNS Name: Specify a second DNS name that resolves to the VIP of Access 
Gateways on the L4 switch. For example, if the DNS name is jwilson.provo.novell.com for 
Access Gateways, you could use heartbeat.jwilson.provo.novell.com for the second name. 


Web Server IP Address: Specify the internal address:127.0.0.1. 

Host Header: Select Forward Received Host Name. This field is not used. 
6 Click OK. 
7 On the Reverse Proxy page, click the new proxy service, then click Web Servers. 
8 Change the Connect Port value on the Web Servers page to 9009. 


The service provider (ESP) in Access Gateway that provides the heartbeat service listens on 
127.0.0.1:9009. 


9 Click Protected Resources. 
10 Click New, then specify a name. 
11 In the URL Path List, click /*, and modify the path to contain the following value: 


/nesp/app/heartbeat 


This is the path to the heartbeat application. 
12 Click OK > OK. 
The heartbeat of this Access Gateway is available from the following URL (See Step 4.): 


http://heartbeat.jwilson.provo.novell.com:81/nesp/app/heartbeat 


High Availability and Fault Tolerance 889 


9.2.4 


13 
14 


If the protected resource is configured with a path of / or /*, the solution works but it can be 
vulnerable to attacks because the configuration opens ESP over a non-SSL port. Restricting the 
resource to /nesp/app/heartbeat automatically denies access to ESP except for the 
heartbeat. 


Click OK and apply the changes to the configuration. 
Add a line similar to the health check script: 


For a Foundry switch, your string must look similar to the following if the hostname is ag1 and the 
IP address is 10.10.16.172: 


healthck agi tcp 
dest-ip 10.10.16.172 
port http 
protocol http 
protocol http url "GET /nesp/app/heartbeat HTTP/1.1\r\nHost:sti60.lab.tst" 
protocol http status-code 200 200 
17-check 


For an Alteon switch, your string must look similar to the following if the hostname is ag1 and the 
IP address is 10.10.16.172: 


open 81, tcp 

send GET /nesp/app/heartbeat HTTP/1.1\r\nHOST:heartbeat.lab. tst\r\n\r\n 
expect HTTP/1.1 200 

close 


Real Server Settings Example 


After setting up the health checks, you need to configure the real server settings. The following is an 
example from a Foundry switch. 


Current real servers settings: 


1: 149.44.171.116, enabled, nane 152, weight 1, tineout 10 mins, naxcon 200090 


backup none, inter Z, retry 4, restr 8 
renote disabled, proxy enabled, submac disabled 
cookie assignnent server: disabled 
exclusionary string natching: disabled 
service ports: 8443 8086 
rcal ports: 
8443: uport 8443, group 1, pbind clientip 
virtual server: 1, 149.44.174.220, enabled 
8030: uport 8080, group 1, pbind clientip 
virtua] server: 1, 149.44.174.220, enabled 


: 149.44.174.51, enabled, nane brie, weight 1, tineout 10 mins, naxcon 200000 


backup none, inter 2, retry 4, restr 6 
renote disabled, proxy enabled, submac disabled 
cookie assignnent server: disabled 
exclusionary string natching: disabled 
service ports: 8443 8086 
real purts: 
8443: uport 8443, group 1, pbind clientip 
virtual server: 1, 149.44.174.220, enabled 
8030: uport 8080, group 1, pbind clientip 
virtual server: 1. 149.44.174.220, enabled 
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9.2.5 Virtual Server Settings Example 


After setting up the real server settings, you need to configure the virtual server settings. The 
following is an example from a Foundry switch. 


surrent virtual servers settings: 
1: 149.494.174.220, enabled, dname idp 
virtual ports: 
6443: rport 6443, group L, pbind clientip, frags 
real servers: 
1: 199.44.171.116, weight 1, enabled, backup none 
2: 199.44.174.51, weight 1, enabled, backup none 
6060: rport 8080, group L, pbind clientip, frags 
real servers: 
1: 149.44.171.116, weight 1, enabled, backup none 
2: 149.44.174.51, weight 1, enabled, backup none 


9.3 Setting up L4 Switch for IPv6 Support 


IPv6 provides large number of available addresses, increased security, and reliability. For supporting 
IPv6, the L4 switch must support addressing both IPv4 and IPv6 as seen in the following figure. 


There is no change in listener configuration for Access Manager devices. Hence, real IP configuration 
and real server group configuration in L4 switch remain the same. Change is required only in the 
virtual server configuration to accept IPv6 connections. 


Figure 9-3 L4 Switch Support For Both IPv4/IPv6 
IPv4/IPv6 IPv4 


Firewall 1 Clustered Firewall 2 LDAP 
Identity Servers S User Stores 


IPv4/IPv6 Administration 
Clients Consoles 


Clustered / RE 
Access Gateways Web Servers 
DMZ 


The existing IPv4 virtual server configuration is as follows: 


¢ server virtual vir-ipv4 10.50.50.1 
¢ predictor round-robin 
+ port 8080 
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+ port 8443 
+ bind 8080 real1 8080 real2 8080 real3 8080 real4 8080 
+ bind 8443 real1 8443 real2 8443 real3 8443 real4 8443 


Use the following procedure to configure the L4 switch for IPv6 support. 


1 Add an IPv6 virtual server for each of the corresponding IPv4 virtual servers: 
¢ server virtual vir-ipv6 2001::1 
+ predictor round-robin 
+ port 8080 
+ port 8443 
+ bind 8080 real1 8080 real2 8080 real3 8080 real4 8080 
+ bind 8443 reali 8443 real2 8443 real3 8443 real4 8443 


NOTE: All real server configurations (real1, real2, real3, real4) in the above sample remains 
same for both IPv4 virtual server and IPv6 virtual server configurations. 


2 (Optional) To use a client IPv6 address for Authorization or Identity Injection Policies, L4 switch 
must be configured to send X-Forwarded-For IP header with each HTTP request. 


IPv6 support is explained in the following scenarios. For simplicity IPv4 information is not provided. 
These scenarios support IPv6 in addition to IPv4. For more information on limitations for this support, 
see Section 9.3.3, “Limitations,” on page 894. 


Web SSO Over IPv6 


Configuration: The L4 switch is configured to listen to the IPv6 Virtual IP addresses for both Access 
Gateway and Identity Server clusters, for example, called IDP-v6 and AG-v6. Identity Server and 
Access Gateway Servers must be configured in the L4 switch for listening to IPv6 requests as actual 
server groups IDP-Group and AG-Group. These groups serve the requests coming to IPv6 addresses 
configured in L4 switch. 


The whole traffic to IDP-v6 and AG-V6 is forwarded to Identity Server and Access Gateway clusters 
respectively with the source IP changed to the IP address of the L4 switch (IPv4-Internal). 


How it works: Incoming traffic to the IDP-v6 and AG-v6 will be redirected to the IDP-Group and AG- 
Group based on load balancing algorithm configured in the L4 switch. The outgoing response traffic 
from Identity Server and Access Gateway Servers to the IPv6 clients will be first routed to IPv4- 
Internal and forwarded back to the client with source IP address of IDP-v6 and AG-v6. The traffic 
initiated from Identity Servers to Access Gateway Servers and vice versa for metadata exchange, 
artifact resolution and so on must also be routed through the L4 switch. Hence, Identity Server and 
Access Gateway Servers must resolve Identity Server and Access Gateway URL to the IPv4 
addresses respectively as they understand only IPv4 addresses. 


For example, if an internal DNS Server is used, then the DNS Server must be configured to resolve 
Identity Server/Access Gateway Server URL. If the IPv4 address for Identity Server is 10.75.75.1 and 
Identity Server URL is www.idp.com, then Identity Server clusters must have 10.75.75.1 
www.idp.com in its hosts file. 


The incoming traffic can be classified into the following: 


¢ Traffic initiated from IPv6 clients. 
¢ Connections initiated from Access Gateway servers to Identity Servers. 
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However, both these can be considered the same as the responses from Identity Server and Access 
Gateway Servers will be using IPv4 address. The L4 switch converts the source to IPv6 address and 
forwards it to the respective remote parties. The clients can either be configured with IPv4 address or 
IPv6 address or both (dual stack). If the client is configured to use IPv6 address only or dual stack, it 
must resolve the published DNS names of Identity Server and Access Gateway Server to the IPv6 
addresses respectively. 


Federated SSO over IPv6 


HTTP Browser clients coming in with IPv6 source address and published DNS names for Identity 
Provider and Service Provider URLs are accessible using IPv6 addresses. There are two ways you 
can access these, the Artifact or Post binding. For more information about these, see “Configuring a 
SAML 2.0 Profile” on page 475, “Configuring a SAML 1.1 Profile” on page 507, and “Configuring a 
Liberty Profile” on page 511. 


Federated SSO over IPv6 Using Artifact Binding 


¢ “Configuration” on page 893 
¢ “How it Works?” on page 893 


Configuration 


The L4 switch is listening in to the IPv6 Virtual IP addresses for Identity Server cluster. Let us call it as 
IDP-v6. The IPv4-Internal in the L4 switch is connected to the actual Identity Server cluster. IDP-v6 
listens to IPv6 clients. The whole traffic to the IDP-v6 will be forwarded to Identity Servers with the 
source IP changed to IPv4-Internal. Identity Servers listen on the IPv4 addresses only. These IPv4 
addresses of Identity Servers must be configured as real server group, say IDP-Group in the L4 
switch. This group must serve the requests coming to IDP-v6 address configured in the L4 switch. 
Incoming traffic to the IDP-v6 addresses will be redirected to the IDP-Group based on the load 
balancing algorithm configured in the L4 switch. 


In case of IDP Servers acting as a Service Provider in an Artifact binding scenario, it needs to resolve 
the Artifact received from the Identity Provider. Hence, the Service Provider must directly contact the 
remote Identity Provider. There will be traffic initiated from the Service Provider in federated SSO 
using Artifact binding. The L4 switch needs another IPv6 interface (IPv6-Internal) to forward 
connections from IPv6 addresses of Identity Servers to IPv6 addresses of remote Identity Providers. 
Identity Server acting as Service Provider must be configured to contain both IPv4 and IPv6 
addresses. This facilitates communication with the IPv6 address of the L4 switch. If Identity Server is 
acting as an Identity Provider, there is no connection initiated from Identity Server even in the artifact 
binding scenario. Hence, an internal IPv6 interface in the L4 switch is not required. 


How it Works? 


The outgoing response traffic from Identity Servers to the IPv6 clients will be first routed to IPv4- 
Internal and forwarded back to the clients with source IP address as IDP-v6 address. 


When an Identity Server is acting as a Service Provider, the traffic will be initiated from the internal 
Identity Servers to the remote Identity Providers. This is routed through the L4 switch and Identity 
Servers must resolve the remote Identity Provider URL to the remote IPv6 address. The DNS server 
configured for Identity Server must be configured to resolve the Identity Provider URL to the remote 
IPv6 address. 
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When Identity Server is acting as an Identity Provider, the incoming traffic to this Identity Server can 
be classified into the following: 

¢ Traffic initiated from IPv6 clients. 

¢ Traffic from the remote Service Provider. 
However, the response from Identity Server uses IPv4 address in both cases. L4 switch converts the 
response to IPv6 address and forwards it to remote IPv6 clients and Service Providers 
respectively. The clients can either be configured with IPv4 address or IPv6 address or both (dual 


stack). If the client is configured to use IPv6 address only or dual stack, it must resolve the published 
DNS name of Identity Server to IDP-v6 address. 


Federated SSO over IPv6 using Post Binding 


¢ “Configuration” on page 894 
+ “How it Works?” on page 894 


Configuration 


The L4 switch is listening in to the IPv6 Virtual IP addresses for Identity Server cluster. Let us call it as 
IDP-v6. The IPv4-Internal in the L4 switch is connected to the actual Identity Server cluster. IDP-v6 
listens to IPv6 clients. The traffic to the IDP-v6 will be forwarded to Identity Servers with the source IP 
changed to |Pv4-Internal. 


Identity Servers listen on the IPv4 addresses only. These IPv4 addresses of Identity Servers must be 
configured as real server group, say IDP-Group in the L4 switch. This group must serve the requests 
coming to IDP-v6 address configured in the L4 switch. Incoming traffic to the IDP-v6 addresses will 
be redirected to the IDP-Group based on the load balancing algorithm configured in the L4 switch. 


Since there is no traffic initiated from the Identity Provider or Service Provider in federated SSO using 
Post binding, Identity Servers must listen only using IPv4 address. 


How it Works? 


The outgoing response traffic from Identity Servers to the IPv6 clients will be first routed to IPv4- 
Internal and forwarded back to the clients with source IP address as IDP-v6 address. 


Since it is Post profile only incoming traffic will be from IPv6 clients. The clients can either be 
configured with IPv4 address or IPv6 address or both (dual stack). If the client is configured to use 
IPv6 address only or dual stack, it must resolve the published DNS name of IDP to IDP-v6 address. 


Limitations 


The following scenarios are not supported: 


Ħ Access Gateways communicating over IPv6 to the Web Servers listening in IPv6 addresses. 
¢ Identity Servers communicating over IPv6 to the LDAP User stores listening in IPv6 addresses. 
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Using a Software Load Balancer 


Instead of using an L4 switch, you can cluster Identity Servers and Access Gateways behind a 
software load balancer that runs in Layer 7. Each manufacturer uses slightly different terminology, but 
the basic steps are quite similar. You need to create the following types of objects: 


+ 


+ 


+ 


+ 


+ 


Pools to specify how load balancing occurs, such as round robin. 


Persistence classes to be used within the pools to enable the sticky bit or to keep state so that a 
connection is sent to the same device. 


Monitors to be used within the pools for monitoring the health heartbeat of the device. 
Virtual servers to set up the ports and protocols for the pools. 
Traffic IP groups where the virtual IP addresses are set up and tied to the virtual servers. 


Because the software actually runs in Layer 7, it does not require any special networking setup and it 
runs on standard server hardware. 


As an example, the following instructions explain how to configure the Zeus ZXTM Load Balancer 
with HTTP and HTTPS for Identity Server and Access Gateway. For more information about this 
product, see Zeus Technology. 


1 Create two persistence classes, one for HTTPS and one for HTTP. 


HTTP > J2EE Session Persistence 
HTTPS > SSL Session ID 


Create four monitors, two for Identity Servers and two for Access Gateways. 

2a Use the following paths to specify a path for HTTP and a path for HTTPS: 
Identity Server: /nidp/app/heartbeat 
Access Gateway: /nesp/app/heartbeat 

2b Configure the following parameters for the monitors: 
HTTP: timeout=10 seconds, use_ssl=no, host_header: <domain>, body_regex: Success 
HTTPS: timeout=10 seconds, use_ssl=yes, host_header: <domain>, body_regex: Success 
Replace <domain> with the DNS name of the Access Manager device 

Create four pools, one for each monitor. Configure each pool with the following parameters: 


Load _balancing: Round Robin 
persistence: <new class created> 
max_reply_time: 10 


For an HTTP resource, replace <new class created> with the HTTP class you created. For an 
HTTPS resource replace <new class created> with the HTTPS class you created. 
Create four virtual servers, one for each port. Configure each with the following parameters: 


Protocol: <scheme> 
Port: <port> 
Pool: <pool created> 


Replace <scheme> with HTTP or HTTPS. 
Replace <port> with one of the following values: 80,8080,443, or 8443. 
Replace <pool created> with one of the pools you created in Step 3. 


5 Create two traffic manager groups, one for Identity Servers and one for Access Gateway. 
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This is where the virtual IP address is set up. 
6 Start the traffic groups. 
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Security And Certificates 


Access Manager includes a certificate management service, which allows you to manage the 
certificates used for digital signatures and data encryption. You can create locally signed certificates 
or import externally signed certificates, then assign these certificates to the trust stores and keystores 
of the following components: 


¢ Identity Server: Certificates allow you to provide secure authentication to Identity Server and 
enable encrypted content from Identity Server portal through HTTPS. They also provide secure 
communications between trusted Identity Servers and user stores. 


+ Access Gateway: Uses server certificates and trusted roots to protect web servers, provide 
single sign-on, and enable the product's data confidentiality features, such as encryption. 


You can install and distribute certificates to Access Manager components and configure how the 
components use certificates. This includes central storage, distribution, and expired certificate 
renewal. 


NOTE: For detailed information about how to secure Access Manager, see NetIQ Access Manager 
4.3 Security Guide . 


e Chapter 10, “Securing Access Manager,” on page 899 

+ Chapter 11, “Setting Up Advanced Session Assurance,” on page 933 

¢ Chapter 12, “Understanding Access Manager Certificates,” on page 941 

e Chapter 13, “Creating Certificates,” on page 947 

¢ Chapter 14, “Managing Certificates and Keystores,” on page 955 

¢ Chapter 15, “Assigning Certificates to Access Manager Devices,” on page 965 
¢ Chapter 16, “Managing Trusted Roots and Trust Stores,” on page 971 

+ Chapter 17, “Enabling SSL Communication,” on page 977 
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Securing Access Manager 


Administration Console contains all the configuration information for all Access Manager 
components. If you federate your users with other servers, it stores configuration information about 
these users. You need to protect Administration Console so that unauthorized users cannot change 
configuration settings or gain access to the information in the configuration store. When you develop 
a security plan for Access Manager, consider the following: 


¢ Section 10.1, “Securing Administration Console,” on page 899 

¢ Section 10.2, “Protecting the Configuration Store,” on page 900 

¢ Section 10.3, “Security Considerations for Certificates,” on page 900 

¢ Section 10.4, “Configuring Secure Communication on Identity Server,” on page 901 
¢ Section 10.5, “Security Considerations for Identity Server,” on page 906 

¢ Section 10.6, “Enabling Secure Cookies,” on page 928 

¢ Section 10.7, “Preventing Cross-site Scripting Attacks,” on page 930 


Securing Administration Console 


When you look for ways to secure Administration Console from unauthorized access, consider the 
following: 


Admin User: The admin user you create when you install Administration Console has all rights to the 
Access Manager components. We recommend that you protect this account by configuring the 
following features: 


+ Password Restrictions: When the admin user is created, no password restrictions are set. To 
ensure that the password meets your minimum security requirements, you should configure the 
standard eDirectory password restrictions for this account. In Administration Console 
Dashboard, click <user name> and then click Manage Roles & Tasks. Click Roles and Tasks > 
Users in the iManager header. Browse to the admin user (found in the novell container), then 
click Restrictions. For configuration help, use the Help button. 


+ Intruder Detection: The admin user is created in the novell container. You should set up an 
intruder detection policy for this container. In Administration Console Dashboard, click <user 
name> and then click Manage Roles & Tasks. Click Roles and Tasks > Directory Administration 
> Modify Object. Select novell, then click OK. Click Intruder Detection. For configuration help, 
use the Help button. 


¢ Multiple Administrator Accounts: Only one admin user is created when you install Access 
Manager. If something happens to the user who knows the name of this user and password or if 
the user forgets the password, you cannot access Administration Console. It is recommended 
that you create at least one backup user and make that user security equivalent to the admin 
user. For instructions, see Section 2.3.1, “Creating Multiple Admin Accounts,” on page 44. For 
other considerations when you have multiple administrators, see Section 2.3, “Managing 
Administrators,” on page 43. 


Network Configuration: You need to protect Administration Console from Internet attacks. It should 
be installed behind your firewall. 
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Delegated Administrators: If you create delegated administrators for policy containers (see 
Section 2.3.3, “Managing Delegated Administrators,” on page 45), be aware that they have sufficient 
rights to implement a cross-site scripting attack using the Deny Message in an Access Gateway 
Authorization policy. 


They are also granted rights to the LDAP server, which gives them sufficient rights to access the 
configuration datastore with an LDAP browser. Modifications done with an LDAP browser are not 
logged by Access Manager. To enable the auditing of these events, see “Activating eDirectory 
Auditing for LDAP Events” on page 49. 


Test Certificates: When you install Administration Console, the following test certificates are 
automatically generated 


test-signing 
test-encryption 
test-connector 
test-provider 
test-consumer 
test-stunnel 


For strong security, we recommend that you replace these certificates, except the test-stunnel 
certificate, with certificates from a well-known certificate authority. 


Ten years after you install Administration Console, new versions of these certificates are 
automatically generated as the old certificates expire. If you are using any of the test certificates in 
your configuration, Administration Console cannot use the new version until you reboot the machine. 


Protecting the Configuration Store 


The configuration store is an embedded, modified version of eDirectory. It is backed up and restored 
with command line options, which back up and restore the Access Manager configuration objects in 
the ou=accessManagerContainer.o=novell object. 


You should back up the configuration store on a regular schedule, and the ZIP file created should be 
stored in a secure place. See Section 28, “Back Up and Restore,” on page 1129. 


In addition to backing up the configuration store, you should also install at least two Administration 
Consoles (a primary and a secondary). If the primary console goes down, the secondary console can 
keep the communication channels open between the various components. You can install up to three 
Administration Consoles. For installation information, see Section 9.1, “Installing Secondary Versions 
of Administration Console,” on page 883. 


The configuration store should not be used for a user store. 


Security Considerations for Certificates 


Your security deployment plan should contain policies for the following: 


¢ Key size for certificates: Access Manager ships with a CA that can create certificates with a 
key size of 512, 1024, 2048, or 4096. Select the maximum size supported by the applications 
that you are protecting with Access Manager. 


¢ Certificate renewal dates: Ensure that you renew certificates before it gets expired. Your 
security needs might allow for a longer or shorter period. 
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¢ Trusted certificate authorities: Access Manager ships with a CA, and during installation of the 
various components, it creates and distributes certificates. For added security, you might want to 
replace these certificates with certificates from a well-known CA. 


NOTE: Access Manager supports SHA-256 and SHA-512 as a signing algorithm. 


For more information about how to import certificates, see Section 13.5, “Importing a Signed 
Certificate,” on page 953. 


Configuring Secure Communication on Identity 
Server 


Identity Server uses the following key pairs for secure communication. In a production environment, 
you should exchange the key pairs that are created at installation time with certificates from a trusted 
certificate authority. 


+ Connector: The test-connector certificate is used when you establish SSL communication 
between Identity Server and the browsers and between Identity Server and Access Gateway for 
back-channel communications. It needs to be replaced with a certificate that has a subject name 
that matches the DNS name of Identity Server. This task is part of basic setup. See Chapter 17, 
“Enabling SSL Communication,” on page 977. 


¢ Signing: The test-signing (by default) key pair is used by the various protocols to sign 
authentication requests, to sign communication with providers on the SOAP back channel, and 
to sign Web Service Provider profiles. For more information about the services that use the 
signing certificate, see “Access Manager Services That Use the Signing Certificate” on 
page 912. 


This certificate can be stored in an external HSM keystore. For information about how to use 
netHSM to replace and manage this signing certificate, see “Using netHSM for the Signing Key 
Pair” on page 911. 


If you want increased security, you can configure signing and encryption certificate for the 
service provider. For information, see Section 10.4.1, “Configuring Enhanced Security for 
Service Provider Communications,” on page 902 


¢ Data Encryption: The test-encryption (by default) key pair is used to encrypt specific fields or 
data in the assertions. For more information about the services that use the encryption 
certificate, see Section 10.4.3, “Viewing Services That Use the Encryption Key PairEncryption,” 
on page 904. 


If you want increased security, you can configure signing and encryption certificate for the 
service provider. For information, see Section 10.4.1, “Configuring Enhanced Security for 
Service Provider Communications,” on page 902. 


To force the browser connections to Identity Server to support a specific level of encryption, see 
Section 17.7, “Configuring the SSL Communication,” on page 996. 


If you are going to use introductions in your federation configuration, you need to set up the following 
key pairs: 


¢ Identity provider: The test-provider key pair is used when you configure your Identity Server to 
use introductions with other identity providers and have set up a common domain name for this 
purpose. It needs to be replaced with a certificate that has a subject name that matches the DNS 
name of the common domain. For configuration information, see “Configuring the General 
Identity Provider Settings” on page 177. 
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¢ Identity consumer: The test-consumer key pair is used when you configure your Identity Server 
to use introductions with other service providers and have set up a common domain name for 
this purpose. It needs to be replaced with a certificate that has a subject name that matches the 
DNS name of the common domain. For configuration information, see “Configuring the General 
Identity Consumer Settings” on page 179. 


To enable secure communication between the user store and Identity Server, you can also import the 
trusted root certificate of the user store. For configuration information, see Section 5.1.1, “Configuring 
Identity User Stores,” on page 360. 


This section describes the following tasks: 


¢ Section 10.4.1, “Configuring Enhanced Security for Service Provider Communications,” on 
page 902 


¢ Section 10.4.2, “Viewing the Services That Use the Signing Key PairSigning,” on page 902 
¢ Section 10.4.3, “Viewing Services That Use the Encryption Key PairEncryption,” on page 904 
¢ Section 10.4.4, “Managing the Keys, Certificates, and Trust Stores,” on page 904 


10.4.1 Configuring Enhanced Security for Service Provider 
Communications 


When a single identity provider authenticates to multiple service providers, all the assertions are 
signed by using a common signing key. The assertions are also decrypted by using a common 
encryption key. Using a single certificate can lead to a vulnerability for all the service providers. 


For example, if the common signing or encryption cert is compromised, the information can be used 
on multiple service providers to potentially gather information. 


To mitigate this risk, you can use a single signing and encryption certificate for each service provider. 


To define signing and encryption certificate for a service provider, see Section 10.4.4, “Managing the 
Keys, Certificates, and Trust Stores,” on page 904 


10.4.2 Viewing the Services That Use the Signing Key PairSigning 


The following services can be configured to use signing: 


¢ Section 10.4.2.1, “Protocols,” on page 903 
¢ Section 10.4.2.2, “SOAP Back Channel,” on page 903 
¢ Section 10.4.2.3, “Profiles,” on page 903 
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10.4.2.1 Protocols 


The protocols can be configured to sign authentication requests and responses. 
To view your current configuration: 


1 Click Devices > Identity Servers > Edit. 


2 In the Identity Provider section, view the setting for the Require Signed Authentication 
Requests option. If it is selected, all authentication requests from service providers must be 
signed. 


3 In the Identity Consumer section, view the settings for the Require Signed Assertions and Sign 
Authentication Requests options. If these options are selected, assertions and authentication 
requests are signed. 


10.4.2.2 SOAP Back Channel 


The SOAP back channel is the channel that the protocols use to communicate directly with a 
provider. The SOAP back channel is used for artifact resolutions and attribute queries for the Identity 
Web Services Framework. 


To view your current configuration for the SOAP back channel: 


1 Click Devices > Identity Servers > Edit. 


2 Select the protocol (Liberty, SAML 1.1, or SAML 2.0), then click the name of an identity provider 
or service provider. 


3 Click Trust. 


4 View the Security section. If the Message Signing option is selected, signing is enabled for the 
SOAP back channel. 


10.4.2.3 Profiles 


Any of the Web Service Provider profiles can be enabled for signing by configuring them to use X.509 
for their message-level security mechanism. 


To view your current configuration: 
1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 
2 Click the name of a profile, then click Descriptions. 


3 Click the Description Name. 


4 If either Peer entity = None, Message=X509 or Peer entity = MutualTLS, Message=X509 has 
been selected as the security mechanism, signing has been enabled for the profile. 
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Viewing Services That Use the Encryption Key 
PairEncryption 


All of the Liberty Web Service Provider Profiles allow you to configure them so that the resource IDs 
are encrypted. By default, no profile encrypts the IDs. 


To view your current configuration: 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 
2 Click the name of a profile. 


3 If the Have Discovery Encrypt This Service’s Resource IDs option is selected, the encryption 
key pair is used to encrypt the resource IDs. 


Managing the Keys, Certificates, and Trust Stores 


You can view the private keys, CA certificates, and certificate containers associated with Identity 
Server configuration. Primarily, you use the Security page to add and replace CA certificates as 
necessary and to perform certificate management tasks, such as adding trusted root certificates to a 
trust store. 


1 Click Devices > Identity Servers > Edit > General > Security. 
2 To view or manage keys and certificates: 
2a Click any of the following links: 


Encryption: Displays the NIDP encryption certificate keystore. The encryption certificate is 
used to encrypt specific fields or data in the assertions. Click Replace to replace the 
encryption certificate. Click Add or Remove to add or remove the encryption certificates. 


Signing: Displays the NIDP signing certificate keystore. The signing certificate is used to 
sign the assertion or specific parts of the assertion. Click Replace to replace the signing 
certificate. Click Add or Remove to add or remove the signing certificates. 


NOTE: When you change the existing signing/encryption certificate, ensure that the 
metadata is reimported from an identity or service provider of another cluster. 


SSL: (Required) Displays the SSL connector keystore. Click this link to access the keystore 
and replace the connector certificate. 


Provider: Displays the ID Provider Introductions SSL Connector keystore. Click this link to 
access the keystore and replace the provider certificate used by Identity Server when it is 
acting as an identity provider. 


Consumer: Displays the ID Consumer Introductions SSL Connector keystore. Click this 
link to access the keystore and replace the consumer certificate used by Identity Server 
when it is acting as an identity consumer (service provider). 


For example, when you click the Provider keystore, the following page appears: 
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Keystore: Provider Introductions SSL Connector 
Keystore name: Provider Introductions SSL Connector 

Keystore type: Java 

Cluster name: idp-corporate 


Cluster/Configuration Members’ Keystores 


Keystore Name Type Device 
ID Provider Introductions SSL Connector Java  10.10.159,206 


Replace... 


C Certificate Alias Subject Replace 


[C] jwilson_provo novell comtomeat CN=jwilson.prova.novell.com [ 
Certificate: 


ålias{es): [tomcat 
OK Cancel 


2b To replace a certificate, click Replace, browse to locate the certificate, then click OK. 
2c If prompted to restart Tomcat, click OK. Otherwise, update Identity Server. 

3 To manage trust stores associated with Identity Server: 
3a Click either of the following links on the Security page: 


NIDP Trust Store: This Identity Server trust store contains the trusted root certificates of all 
the providers that it trusts. Liberty and SAML 2.0 protocol messages that are exchanged 
between identity and service providers often need to be digitally signed. A provider uses the 
signing certificate included with the metadata of a trusted provider to validate signed 
messages from the trusted provider. The trusted root of the CA that created the signing 
certificate for the service provider needs to be in this trust store. 


To use SSL for protocol messages to be exchanged between providers, each provider must 
trust the SSL certificate authority (CA) of the other provider. You must import the root 
certificate chain for the other provider. Failure to do so causes numerous system errors. 


OCSP Trust Store: Identity Server uses this trust store for OCSP certificates. Online 
Certificate Status Protocol is a method used for checking the revocation status of a 
certificate. To use this feature, you must set up an OCSP server. Identity Server sends an 
OCSP request to the OCSP server to determine if a certain certificate has been revoked. 
The OCSP server replies with the revocation status. If this revocation checking protocol is 
used, Identity Server does not cache or store the information in the reply, but sends a 
request every time it needs to check the revocation status of a certificate. The OCSP reply 
is signed by the OCSP server. To verify that it was signed by the correct OCSP server, the 
OCSP server certificate needs to be added to this trust store. The OCSP server certificate 
itself is added to the trust store, not the CA certificate. 


For example, if you click the NIDP Trust Store, the following page appears: 
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Trust Store: Trust Store 
Trust store name: Trust Store 
Trust store type: Java 


Cluster name: idp-corporate 


Cluster Members’ Trust Stores 


Trust Store Name Type Device 
Trust Store Java 10.10,159,206 


Trusted Roots 


Add... | Remove | Auto-lmport From Server... 
C] Trusted Root Alias Subject Auto-Import From Server 
E] configca configC4 O=jwilson_tree, OU=Organizational CA Server IP/DNS: 


Server Port: 


OK Cancel 


3b Select one of the following actions: 


+ To add a trusted root that you have already imported, click Add, click the Select 
Trusted Roots icon, select the trusted root, then click OK twice. 


+ To import the trusted root from the server, click Auto-lmport From Server, specify the 
server's IP address or DNS name and port, then click OK. The auto-import displays the 
certificate chain, which you can select for import. 


+ To remove a trusted root, select the trusted root, then click Remove. 


For more information about enabling security for a basic Access Manager configuration, see 
Chapter 17, “Enabling SSL Communication,” on page 977. 


For additional information about managing certificates, see Chapter 14, “Managing Certificates and 
Keystores,” on page 955. 


Security Considerations for Identity Server 


By default, all Access Manager components (Identity Server and Access Gateway) trust the 
certificates signed by the local CA. We recommend that you configure Identity Server to use an SSL 
certificate signed externally, and that you configure the trusted store of the Embedded Service 
Provider for each component to trust this new CA. See Chapter 15, “Assigning Certificates to Access 
Manager Devices,” on page 965. 


You can increase security of Identity Server by considering the following topics: 


¢ Section 10.5.1, “Federation Options,” on page 907 

¢ Section 10.5.2, “Authentication Contracts,” on page 907 

¢ Section 10.5.3, “Forcing 128-Bit Encryption,” on page 908 

¢ Section 10.5.4, “Configuring the Encryption Method for the SAML Assertion,” on page 909 
¢ Section 10.5.5, “Configuring SAML 2.0 to Sign Messages,” on page 909 

¢ Section 10.5.6, “Blocking Access to Identity Server Pages,” on page 911 

¢ Section 10.5.7, “Using netHSM for the Signing Key Pair,” on page 911 
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Federation Options 


When you set up federation between an identity provider and a service provider, you can select either 
to exchange assertions with a post method or to exchange artifacts. 


+ An assertion in a post method might contain the user’s password or other sensitive data, which 
can make it less secure than an artifact when the assertion is sent to the browser. It is possible 
for a virus on the browser machine to access the memory where the browser decrypts the 
assertion. 


¢ An artifact is a randomly generated ID, it contains no sensitive data, and only the intended 
receiver can use it to retrieve assertion data. 


If both providers support artifacts, you should select this method because it is more secure. For more 
details, see the Response protocol binding option in “Configuring a SAML 2.0 Authentication 
Request” on page 483 and Section 5.2.6.6, “Configuring a Liberty Authentication Request,” on 

page 513. 


For more information about how to setup federation, see Section 5.2.1, “Configuring Federation,” on 
page 429. 


Authentication Contracts 


By default, Administration Console allows you to select from the following contracts and options when 
specifying whether a resource requires an authentication contract: 


+ None: Allows public access to the resource and does not require authentication contract. 


+ Name/Password - Basic: Requires that the user enter a name and password that matches an 
entry in an LDAP user store. The credentials do not need to be sent over a secure port. This 
uses the unprotected BasicClass, which is not recommended for a production environment. 


+ Name/Password - Form: Requires that the user enter a name and password that matches an 
entry in an LDAP user store. The credentials do not need to be sent over a secure port, although 
they can be if the user is configured for HTTPS. This contract uses the unprotected 
PasswordClass, which is not recommended for a production environment. 


¢ Secure Name/Password - Basic: Requires that the user enter the name and password from a 
secure (SSL) connection. This uses the ProtectedBasicClass, which is recommended for a 
production environment. 


¢ Secure Name/Password - Form: Requires that the user enter the name and password from a 
secure (SSL) connection. This uses the ProtectedPasswordClass, which is recommended for a 
production environment. 


+ Any Contract: Allows the user to use any contract defined for Identity Server configuration. 


If you have set up the Access Manager to require SSL connections among all of its components, you 
should delete the Name/Password - Form and the Name/Password - Basic contracts. This removes 
them from the list of available contracts when configuring protected resources and prevents them 
from being assigned as the contract for a protected resource. If these contracts are assigned, the 
user's password can be sent across the wire in clear text format. At some future date, if your system 
needs this type of contract, you can re-create it from the method. To delete these contracts, go to 
Administration Console and click Identity Servers > Servers > Edit > Local > Contracts. 
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All client communication with Identity Server currently uses 128-bit encryption. If the browser is 
unable to support 128 bit encryption, the user is not allowed to authenticate. You can modify the 
supported encryption level by adding or removing the ciphers listed in the server.xml file. 


1 Ata command prompt, change to the Tomcat configuration directory: 
Linux: /opt/novell/nam/idp/conf 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat\conf 


2 To edit the server.xml entries, search for the cipher attribute in the <Connector> element 
and then modify the list of ciphers based on your needs. For example, a sample configuration to 
enable 128-bit encryption will be as follows: 


ciphers="SSL_RSA_WITH_RC4_128 MD5, SSL_RSA_WITH_RC4_128_ SHA, 
TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128 CBC_SHA, 
TLS_DHE_DSS_WITH_AES_128_CBC_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA, 
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA, 
TLS_KRB5_WITH_3DES_EDE_CBC_SHA, TLS_KRB5_WITH_RC4_128 SHA" 


This is a comma-separated list of the JSSE names for the TLS cipher suites. 


IMPORTANT: If you enter a cipher name incorrectly, Tomcat reverts to the default values, which 
allow the weak ciphers to be used. 


If you want to allow the SSL cipher suites, the following JSSE names can be added to the list: 


SSL_RSA_WITH_RC4_128_MD5 
SSL_RSA_WITH_RC4_128 SHA 


For a complete list of supported cipher suites and their requirements, see The SunJSSE 
Provider. 


3 To activate the cipher list, restart Tomcat. 
Linux: Enter one of the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
Windows: Enter the following commands: 
net stop Tomcat7 
net start Tomcat7 


4 (Conditional) If you have multiple Identity Servers in your cluster configuration, repeat these 
steps on each Identity Server. 


Preventing Automatically Changing the Session ID 


1. Click Devices > Identity Servers > Edit > Options > New. 
2. Set the RENAME SESSION ID property to false. 
3. Restart Tomcat on each Identity Server in the cluster. 
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Configuring the Encryption Method for the SAML Assertion 


By default, AES128 (Advanced Standard Encryption, 128-bit) is used to encrypt SAML assertions. If 
you require a different encryption method, such as TDES (Triple Data Encryption Algorithm) or 
AES256 (Advanced Standard Encryption, 256-bit), you can modify the Tomcat web. xm1 file and 
specify your required method. To use PKCS 2.0 (RSA-OAEP) for encryption, see TID. 
1 Open the web.xml file. 
Linux: /opt/novell/nam/idp/webapps/nidp/WEB- INF/ 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- INF/ 


2 Add the following lines to the file: 


<context -param> 
<param-name>EncryptionMethod</param-name> 
<param-value>TDES</param-value> 

</context -param> 


You can set the <param-value> element to TDES, AES128, or AES256. Because AES 128 is the 
default, specifying this value in the web.xml file does not change any behavior. 
3 Save the file and copy it to each Identity Server in the cluster. 
4 Restart Tomcat on each Identity Server in the cluster. 
Linux: Enter the following command: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
Windows: Enter the following commands: 
net stop Tomcat7 


net start Tomcat7 
The following algorithms for encryption method are supported: 


<md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/ 
><md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/ 
><md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/ 
><md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep"/ 
><md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgfip"/ 
> 


Configuring SAML 2.0 to Sign Messages 


In conformance with the SAML 2.0 specification, Identity Server does not require the signing post 
messages. However, if you want this extra layer of security, you can configure Identity Server to sign 
SAML 2.0 post messages. This is a global option, and when enabled, all SAML 2.0 service providers 
sign post messages. 


To enable the signing of post messages: 


1 Open the web.xml file. 

Linux: /opt/novell/nam/idp/webapps/nidp/WEB- INF/ 

Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- INF/ 
2 Add the following lines to the file: 
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<context -param> 
<param-name>SignPost</param-name> 
<param-value>true</param-value> 
</context -param> 


3 Save the file and copy it to each Identity Server in the cluster. 
4 Restart Tomcat on each Identity Server in the cluster. 

Linux: Enter one of the following commands: 

/etc/init.d/novell-idp restart 

rcnovell-idp restart 

Windows: Enter the following commands: 

net stop Tomcat7 

net start Tomcat7 


You can configure the Identity Server to sign SAML 2.0 post messages for one or multiple trust 
providers. 


To enable the signing of post messages for specific trust providers: 


Enable the following properties in the Administration Console. For information about how to set 
properties in the Administration Console, see “Configuring Identity Server Global Options” on page 75 
and “Defining Options for SAML 2.0” on page 487. 


IS SAML2 POST SIGN RESPONSE: Specify true to enable the identity provider to send signed 
SAML 2.0 post responses to all its trusted providers. 


NOTE: Configuring IS SAML2 POST SIGN RESPONSE is same as configuring the SignPost in 
web.xml. However, configuring it through the Administration Console is recommended because it 
provides more options. You can combine these options with IS SAML2 POST SIGN RESPONSE to 
avoid Access Manager restarts. 


SAML2 POST SIGN RESPONSE TRUSTEDPROVIDERS: Specify one or more trusted provider's 
entityID. Set the value as true to verify the signed SAML 2.0 post responses. 


Avoiding Assertion Signing Validation 


You can enable the SAML2 AVOID SIGN AND VALIDATE ASSERTION TRUSTEDPROVIDERS 
option on both identity provider and service provider. 


If this flag is set on the identity provider, then the complete POST message (excluding the assertion) 
is signed. 


If this option is set on the service provider, then the signature of the POST message is verified but the 
assertion signature is not verified. If this option is not set on the service provider and an identity 
provider sends an assertion where only the assertion is signed, the service provider cannot validate 
it. 

To avoid the assertion signing or validation, perform the following procedure at identity provider/ 
service provider. 


1 In Administration Console, click Identity Server > Edit > SAML 2.0 > Service Provider or Identity 
Provider > Options > New. 


2 Select SAML2 AVOID SIGN AND VALIDATE ASSERTION TRUSTEDPROVIDERS and specify 
the value in this format: entityID of the identity provider, entityID2 of the service provider. 
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NOTE: The entityID of the identity provider and the service provider are comma-separated 
values. 


For example, to enable this flag on the identity provider use the following format: https:// 
www.idp.com:8443/nidp/saml/metadata 


For example, to enable this flag on the service provider use the following format: https:// 
www.sp.com:8443/nidp/saml/metadata 


3 Save the configuration. 
4 Restart Identity Server. For restarting, see Step 4 on page 909. 


When this flag is set in the service provider, the SAML 2.0 POST response is signed and assertion is 
not signed. The service provider will accept the response instead of returning an error. 


Blocking Access to Identity Server Pages 


Identity Server has a couple of pages that authenticated users can access and which contain 
information about the user and Identity Server that some security models deem sensitive. If you want 
to block user access to these pages, see the following sections: 


+ “Blocking Access to the User Portal Page” on page 426 
¢ “Blocking Access to the WSDL Services Page” on page 427 


Using netHSM for the Signing Key Pair 


netHSM is a Hardware Security Module (HSM) from nCipher. The module is attached to the network 
and provides cryptographic resources for multiple servers. Keys stored in a netHSM keystore are 
secure because the key material can never be exposed outside of the module. 


Access Manager has not been tested with any other HSM products; it has only been tested with the 
netHSM module from nCipher. 


Figure 10-1 illustrates a simple netHSM configuration with an Identity Server as a netHSM client. 


Figure 10-1 A Simple netHSM Configuration 
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Access Manager allows you to use netHSM to store and manage the signing key pair of Identity 
Server. You must use Administration Console to store and manage the other Access Manager 
certificates. Access Manager uses the Java Security provider of the netHSM server to interact with 
the netHSM server. 
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This section describes the topics: 


¢ Section 10.5.7.1, “Understanding How Access Manager Uses Signing and Interacts with the 
netHSM Server,” on page 912 


¢ Section 10.5.7.2, “Configuring Identity Server for netHSM,” on page 914 


NOTE: This implementation uses a single netHSM signing certificate. For information about how to 
use multiple signing certificates, see Section 14.8, “Using Multiple External Signing Certificates,” on 
page 962. 


Understanding How Access Manager Uses Signing and Interacts 
with the netHSM Server 


The netHSM server provides a signing certificate that is used instead of the one provided by Access 
Manager. Requests, responses, assertions, or payloads can be signed when there are interactions 
during single sign-on or during attribute queries between service providers and identity providers 
using any of the SAML1.1, SAML2, Liberty ID-FF, Liberty ID-WSF, or ID-SIS protocols. 


Access Manager Services That Use the Signing Certificate 


The following services can be configured to use signing: 


Protocols 
The protocols can be configured to sign authentication requests. 
To view your current configuration: 


1 Click Devices > Identity Servers > Edit. 


2 In the Identity Provider section, view the setting for the Require Signed Authentication 
Requests option. If it is selected, all authentication requests from identity providers are signed. 


3 In the Identity Consumer section, view the settings for the Require Signed Assertions and Sign 
Authentication Requests options. If these options are selected, assertions and authentication 
requests are signed. 


The SOAP back channel is the channel that the protocols use to communicate directly with a 
provider. The SOAP back channel is used for artifact resolutions and attribute queries for the Identity 
Web Services Framework. 


To view your current configuration for the SOAP back channel: 


1 Click Devices > Identity Servers > Edit. 


2 Select the protocol (Liberty, SAML 1.1, or SAML 2.0), then click the name of an identity provider 
or service provider. 


3 Click Access. 


4 View the Security section. If the Message Signing option is selected, signing is enabled for the 
SOAP back channel. 


Profiles 


Any of the Web Service Provider profiles can be enabled for signing by configuring them to use X.509 
for their security mechanism. 
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To view your current configuration: 


1 Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 
2 Click the name of a profile, then click Descriptions. 
3 Click the Description Name. 


4 If either Peer entity = None, Message=X509 or Peer entity = MutualTLS, Message=X509 has 
been selected as the security mechanism, signing has been enabled for the profile. 


Understanding the Interaction of the netHSM Server with Access Manager 


Figure 10-2 outlines one of the basic flows that might occur during single sign-on to Identity Server 
when authentication requests have been configured for signing. 


Figure 10-2 Basic Flow for an Authentication Request Using netHSM 
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1. The user requests Access Gateway to provide access to a protected resource. 


2. Access Gateway redirects the user to Identity Server, which prompts the user for a username 
and password. 


3. Identity Server authenticates the user. If signing is enabled, the payload is signed by the netHSM 
server through the Java JSSE security provider. 


4. Identity Server returns the authentication artifact to Access Gateway. 


5. The Embedded Service Provider of Access Gateway retrieves the user’s credentials from 
Identity Server. 


6. Access Gateway verifies that the credentials allow the user access to the resource, then sends 
the request to the Web server. 


7. The Web server returns the requested Web page. 
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Configuring Identity Server for netHSM 


“Prerequisites for Using netHSM” on page 914 

“Configuring Identity Server to Be a netHSM Client’ on page 914 
“Creating the nCipher Signing Key Pair’ on page 916 

“Configuring Identity Server to Use the netHSM Certificate” on page 921 
“Verifying the Use of the nCipher Key Pair” on page 925 
“Troubleshooting the netHSM Configuration” on page 925 


Prerequisites for Using netHSM 


o 
o 
o 


An installed and configured netHSM server. 
An installed and configured remote file system with the netHSM client. 
An installed Identity Server, assigned to a cluster configuration. 


For instructions on a basic setup that assigns Identity Server to a cluster configuration, see 
Section 3.3, “Configuring an Identity Server,” on page 59. 


The following instructions describe one way to integrate Identity Server with a netHSM server. Other 
ways are possible. 


Configuring Identity Server to Be a netHSM Client 


The following instructions are based on nCipher hardware, but you should be able to adapt them for 
your hardware. The instructions explain how to configure Identity Server so that it can communicate 
with both the nCipher server and the remote file system server, how to create a signing key pair and 
its keystore, how to copy these to Identity Server, and how to synchronize the changes with the 
remote file system server. 


1 


At Identity Server, log in as the root or administrator user and install the netHSM client software. 


The nCipher software installs files in the /opt/nfast directory on Linux and in the C:\nfast 
directory on Windows. It creates an nfast user and group. Check your netHSM documentation 
for the specific steps. 


(Conditional) If your Identity Server cluster configuration contains more than one Identity Server, 
install the netHSM client software on the other Identity Servers in the cluster. 


At the netHSM server, configure the server to allow Identity Server to be a client. 
Check your netHSM documentation for the specific steps. 


(Conditional) If your Identity Server cluster configuration contains more than one Identity Server, 
configure the netHSM server to allow the other Identity Servers in the cluster to be a client. 


At Identity Server, enroll the client to use the server: 
5a To get the ESN and hash numbers for the enroll command, enter the following command: 
Linux: /opt/nfast/bin/anonkneti <IP_address> 
Windows: C:\nfast\bin>anonkneti <IP_address> 
Replace </P_address> with the IP address of the netHSM server. 
5b To enroll the client, enter the following command: 
Linux: /opt/nfast/bin/nethsmenroll -p <IP_address> <ESN> <hash> 
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Windows: C:\nfast\bin>nethsmenroll -p <IP_address> <ESN> <hash> 


Replace </P_address> with the IP address of the netHSM server. Replace <ESN> and 
<hash> with the values copied from the anonkneti command. 


6 (Conditional) If Identity Server and Administration Console are installed on the same machine, 
modify the 9000 and 9001 TCP ports: 


6a Ina text editor, open the sc.conf file located in the following directory: 
Linux: /opt/novell/devman/share/conf 


Windows Server 2012: \Program Files (x86)\Novell\Tomcat\webapps\roma\ WEB- 
INF\conf 


6b Change the ports from 9000 and 9001 to another value, such as 9010 and 9011. 
The lines should look similar to the following: 


<stringParam name="ExecutorPort" value="9010" /> 
<stringParam name="SchedulerPort" value="9011" /> 


6c Save the changes. 

6d Restart Tomcat: 
Linux: Enter one of the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 
Windows: Enter the following commands: 
net stop Tomcat7 
net start Tomcat7 


6e (Conditional) If other Identity Servers in the cluster contain an Administration Console, 
repeat Step 6. 


7 At Identity Server, enable the netHSM client so that it uses TCP: 
7a Enter the following command: 
Linux: /opt/nfast/bin/config-serverstartup -sp 
Windows: C:\nfast\bin>config-serverstartup -sp 
7b To restart the nfast client: 
Linux: Enter the following command: 
/opt/nfast/sbin/init.d-nfast restart 
Windows: Enter the following commands: 
C:\nfast\bin>net stop "nfast server" 
C:\nfast\bin>net start "nfast server" 


8 Configure communication to the remote file system server. In this sample configuration, the 
remote file system is installed on a Windows machine. 


8a At the remote file system server, enable communication with Identity Server. For a Windows 
machine, enter the following command: 


C:\nfast\bin\rfs-setup.exe --gang-client --write-noauth <address> 


Replace <address> with the IP address of Identity Server. 


8b At Identity Server, enable communication with the remote file system server. For nCipher, 
enter the following command: 


Linux: /opt/nfast/bin/rfs-sync --setup --no-authenticate <address> 
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Windows: C:\nfast\bin>rfs-sync --setup --no-authenticate <address> 
Replace <address> with the IP address of the remote file system server. 
8c At Identity Server, initialize synchronization with the remote file system server. 
Linux: Enter the following commands: 
/opt/nfast/bin/rfs-sync --update 
/opt/nfast/bin/rfs-syne --commit 
Windows: Enter the following commands: 
C:\nfast\bin>rfs-sync --update 
C:\nfast\bin>rfs-synce --commit 


The first command reads updates from the remote file system server and downloads files to 
the /opt/nfast/kmdata/local directory on Linux and the C: \nfast\kmdata\local 
directory on Windows. The second command writes local changes to the remote file system 
server. 


9 Continue with “Creating the nCipher Signing Key Pair” on page 916. 


Creating the nCipher Signing Key Pair 


IMPORTANT: Because of Access Manager configuration conflicts, you need to use a netHSM client 
other than Identity Server. The remote file system server is a netHSM client, or if you have configured 
another device as a client, you can use that device. 


The following commands are specific to nCipher; it does not come with a tool to generate a key pair 
and CSR. nCipher also uses a unique keystore of type nCipher . sworld. 


nCipher supports both a Windows and a Linux netHSM client. 
+ If you have a Windows netHSM client, the command is located in the following directory: 
c:\Program Files\Java\jdk1.5.0_14\jre\bin\java 
¢ If you have Linux netHSM client, the command is located in the following directory: 
/opt/novell/java/bin/java 
To create a new key pair for nCipher: 


1 Ona netHSM client, add the nCipher provider to the provider list of the java.security file: 


1a In a text editor, open the C:\Program Files\Java\jdk1.5.0_14\jre\lib\ 
security\java.security file. 


1b Add the following lines to the top of the list of providers: 


security.provider .1=com.ncipher.fixup.provider .nCipherRSAPrivateEncrypt 
security.provider .2=com.ncipher.provider .km.nCipherkM 


The provider section should look similar to the following: 
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# 


# List of providers and 


# 


security. 
security. 
security. 
security. 
security. 
security. 
security. 
security. 


provider. 
provider. 
provider. 


provider 


1c Save your changes. 
2 Add the nfast libraries to the CLASSPATH for Java: 
For a Windows client, add the following paths: 


1=com 


3=sun 


5=com 


7=sun 


their preference orders (see above): 


.ncipher.fixup.provider .nCipherRSAPrivateEncrypt 
2=com. 


ncipher.provider.km.nCipherkM 


.security.provider.Sun 
.4=sun. 
provider. 
provider. 
provider. 
provider. 


security.rsa.SunRsaSign 


.sun.net.ssl.internal.ssl.Provider 
6=com. 


sun.crypto.provider .SunJCE 


.security.jgss.SunProvider 
8=com. 


sun.security.sasl.Provider 


c:\nfast\java\classes\keysafe.jar;c:\nfast\java\classes\nfjava.jar 
;c:\nfast\java\classes\kmjava.jar;c:\nfast\java\classes\kmcsp. jar; 
c:\nfast\java\classes\jutils.jar;c:\nfast\java\classes\jcetools. 

jar;c:\nfast\java\classes\spp.jar;c:\nfast\java\classes\rsaprivenc 


.jar; 


For a Linux client, add the following paths and export them: 


/opt/nfast/java/classes/nfjava.jar:/opt/nfast/java/classes/ 
kmjava.jar:/opt/nfast/java/classes/kmcsp.jar:/opt/nfast/java/ 
classes/spp.jar:/opt/nfast/java/classes/rsaprivenc.jar:/opt/nfast/ 
java/classes/jutils.jar:/opt/nfast/java/classes/jcetools.jar:/opt/ 
nfast/java/classes/keysafe. jar 


3 Create a directory for the keystore and change to that directory. 


4 Ona Windows client, enter the following command to create a new key in a keystore: 


"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module 
-DignorePassphrase=true sun.security.tools.KeyTool -genkey -v 
-alias od93 -keyalg RSA -keystore AMstore.jks -storetype 
nCipher.sworld -provider com.ncipher.provider.km.nCipherkM 


Enter your values for the following parameters: 
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Parameter 


-Dprotect=module 


-DignorePassphrase=true 


sun.security.tools.KeyTool 


-alias 


-keyalg 


-keystore 


-storetype 


-provider 


Description 


Required if you want the keystore to be module 
protected. 


Required if you want the keystore to be module 
protected. 


The name of the keytool command 


Aname that helps you identify the key. In this 
sample configuration, the name is 0d93. 


The security algorithm. 


Aname for the keystore. In this sample 
configuration, the name is AMstore. jks. 


The type of keystore. For nCipher, this must be set 
to nCipher.sworld. 


The name of the providerClass and providerName. 
This is the provider that you added to the 
java.security file in Step 1. 


The tool prompts you for a password for the keypass and the storepass. They must be the same 
password if you are going to use card set protection rather than module protection. 


The tool also prompts you for the certificate subject name (first name, last name, organization, 
organizational unit, locality, state or providence, and country). 


5 To generate a certificate request from a key in the keystore, enter the following command: 


"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module 
-DignorePassphrase=true sun.security.tools.KeyTool -certreq -alias 
od93 -file cert.csr -keypass mypwd -keystore AMstore.jks -storepass 
mypwd -storetype nCipher.sworld -provider 


com.ncipher .provider .km.nCipherKM 


Enter your values for the following parameters: 


Parameter 


-Dprotect=module 


-DignorePassphrase=true 


sun.security.tools.KeyTool 
-certreq 


-alias 


-file 
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Description 


Required if you want the keystore to be module 
protected. 


Required if you want the keystore to be module 
protected. 


The name of the keytool command 
The parameter that makes this a certificate request. 


A name that helps you identify the certificate 
request. In this sample configuration, the name is 
od93. 


The name to be given to the certificate signing 
request file. In this sample configuration, the name 
is cert.csr. 


Parameter Description 


-keypass The password for the key. In this sample 
configuration, the password is mypwd. 


-keystore Aname for the keystore. In this sample 
configuration, the name is AMstore. jks. 


-storepass The password for the keystore. In this sample 
configuration, the password is mypwd. 


-storetype The type of keystore. For nCipher, this must be set 
to nCipher.sworld. 


-provider The name of the providerClass and providerName. 


6 Take the CSR created in Step 5 to a certificate authority. The CA needs to send you a DER- 
encoded public certificate. The CA also needs to send you the public certificate that it used to 
create the certificate and the public certificates for any CAs in the chain. 


7 Load the public certificate of the CA into the keystore by entering the following command: 
"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module 
-DignorePassphrase=true sun.security.tools.KeyTool -import -alias 


publicca -file certca.cer -keystore Amstore.jks -storetype 
nCipher.sworld -provider com.ncipher.provider.km.nCipherkKM 


Enter your values for the following parameters: 


Parameter Description 

-Dprotect=module Required if you want the keystore to be module 
protected. 

-DignorePassphrase=true Required if you want the keystore to be module 
protected. 

sun.security.tools.KeyTool The name of the keytool command 

-import The parameter that makes this an import request. 

-alias Aname that helps you identify that this is the public 


certificate from the CA. In this sample configuration, 
the name is publicca. 


-file The name of the CA certificate file. In this sample 
configuration, the name is certca.cer. 


-keystore Aname for the keystore. In this sample 
configuration, the name is AMstore. jks. 


-storetype The type of keystore. For nCipher, this must be set 
to nCipher.sworld. 


-provider The name of the providerClass and providerName. 


The tool prompts you for the keystore password and asks whether you want to trust the 
certificate. 


8 (Conditional) Repeat Step 7 for each CA in the chain, giving each CA a unique alias. 
9 Import the signed certificated received from the CA by entering the following command: 
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"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module 
-DignorePassphrase=true sun.security.tools.KeyTool -import -alias 
od93 -file signcert.der -keystore AMstore.jks -storepass mypwd 
-storetype nCipher.sworld -provider 
com.ncipher.provider.km.nCipherkM 


Enter your values for the following parameters: 


Parameter Description 

-Dprotect=module Required if you want the keystore to be module 
protected. 

-DignorePassphrase=true Required if you want the keystore to be module 
protected. 

sun.security.tools.KeyTool The name of the keytool command 

-import The parameter that makes this an import request. 

-alias Aname that helps you identify that this is the 


signing key pair from the CA. It needs to be the 
same alias you specified when you created the 
keystore in Step 4. In this sample configuration, the 
name is 0d93. 


-file The name of the signing certificate file from the CA. 
In this sample configuration, the name is 
signcert.der. 


-keystore Aname for the keystore. In this sample 
configuration, the name is AMstore. jks. 


-storepass The password for the keystore. In this sample 
configuration, the password is mypwd. 


-storetype The type of keystore. For nCipher, this must be set 
to nCipher.sworld. 


-provider The name of the providerClass and providerName. 


(Optional) To verify that the certificates have been added to the keystore, enter the following 
command: 


"c:\Program Files\Java\jdk1.5.0_14\jre\bin\java" -Dprotect=module 
-DignorePassphrase=true sun.security.tools.KeyTool -list -v 
-keystore AMstore.jks -storetype nCipher.sworld -provider 
com.ncipher.provider.km.nCipherkM 


The keystore should contain at least two certificates. The certificate that you created should now 
be issued by the CA you used, and the public certificate of the CA should be there as the owner 
and the issuer. 


Copy the keystore to the idp directory on Identity Server. 
Linux: /opt/novell/devman/jcc/certs/idp 
Windows Server 2012: \Program Files (x86)\Novell\devman\jcc\certs\idp 


The keystore is found on the netHSM client in the directory specified by the -keystore 
parameter when you created the keystore. See Step 4. 


Synchronize Identity Server with the remote file system server. 
Linux: Enter the following commands: 
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/opt/nfast/bin/rfs-sync --update 
/opt/nfast/bin/rfs-syne --commit 
Windows: Enter the following commands: 
C:\nfast\bin>rfs-sync --update 
C:\nfast\bin>rfs-synce --commit 


13 (Conditional) If the cluster configuration contains more than one Identity Server, complete the 
following steps for each cluster member: 


13a Copy the keystore to the cluster member. Copy it to the following directory: 

Linux: /opt/novell/devman/jcc/certs/idp 

Windows Server 2012: \Program Files (x86)\Novell\devman\jcc\certs\idp 
13b Ensure that the novlwww user has at least read rights. 


13c Use the netHSM client to synchronize the cluster member with the remote file system 
server. 


Linux: Enter the following commands: 
/opt/nfast/bin/rfs-sync --update 
/opt/nfast/bin/rfs-syne --commit 
Windows: Enter the following commands: 
C:\nfast\bin>rfs-sync --update 
C:\nfast\bin>rfs-sync --commit 


14 Continue with “Configuring Identity Server to Use the netHSM Certificate” on page 921. 


Configuring Identity Server to Use the netHSM Certificate 


The procedure to modify the classpath names depends upon whether you have a Linux or a Windows 


Identity Server: 
Configuring a Linux Identity Server for the Certificate 


1 At Identity Server, log in as root. 
2 Add the nfast jar files to the classpath. 


Because Identity Server runs as a Tomcat service, the following steps explain how to modify the 


classpath for Tomcat. 
2a In an editor, open the /opt/novell/nam/idp/bin/dtomcat7 file. 


2b To the CLASSPATH="$JAVA_HOME"/1ib/tools. jar line, add the following classes from the 


/opt/nfast/java/classes directory: 


nfjava.jar 
kmjava. jar 
kmcsp. jar 
spp.jar 
rsaprivenc. jar 
jutils.jar: 
jcetools.jar 
keysafe. jar 


Your line should look similar to the following: 
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CLASSPATH="$JAVA_HOME"/1ib/tools.jar:/opt/nfast/java/classes/ 
nfjava.jar:/opt/nfast/java/classes/kmjava.jar:/opt/nfast/java/ 
classes/kmcsp.jar:/opt/nfast/java/classes/spp.jar:/opt/nfast/ 


java/classes/rsaprivenc.jar:/opt/nfast/java/classes/ 
jutils.jar:/opt/nfast/java/classes/jcetools.jar:/opt/nfast/ 
java/classes/keysafe. jar 


2c Save your changes. 


3 Add the novlwww user to the nfast group by entering the following command: 


usermod novlwww -G nfast 


4 Add the netHSM certificate configuration lines to the tomcat7.conf file: 


4a In a text editor, open the opt/novell/nam/idp/conf/tomcat7.conf file. 


4b Add the following lines: 


JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.nidp.extern.config.file= 
/opt/novell/nids/1lib/webapp/WEB-INF/classes 
externKeystore.properties" 


JAVA_OPTS="${JAVA_OPTS} -Dprotect=module 
-DignorePassphrase=true" 


The first line specifies the location of the properties file. You can specify another location. 


The second line is required only if you want the keystore to be module protected rather than 


card protected. 


5 Configure the externKeystore.properties file to use the nCipher key and keystore: 


5a In a text editor, create an externKeystore. properties file in the /opt/novell/nam/idp/ 
webapps/nidp/WEB-INF/classes directory. 


If you specified a different location for this file in Step 4, use that location. 


5b Add the following lines: 


com.novell.nidp.extern. 


erkKM 


com.novell.nidp.extern. 
com.novell.nidp.extern. 
com.novell.nidp.extern. 


idp/AMstore.jks 


com.novell.nidp.extern. 
com.novell.nidp.extern. 
com.novell.nidp.extern. 
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signing. 


Signing. 
Signing. 
Signing. 


Signing. 
signing. 
Signing. 


providerClass=com.ncipher.provider .km.nCiph 


providerName=nCipher kM 
keystoreType=nCipher . sworld 
keystoreName=/opt/novell/devman/jcc/certs/ 


keystorePwd=mypwd 
alias=od93 
keyPwd=mypwd 


Enter your values for the following variables: 


Variable Value 


<provider_class> The name of the providerClass. For nCipher, this must be set to 
com.ncipher.provider .km.nCipherkM. 


<provider_name> The name of the provider. For nCipher, this must be set to nCipherkM. 
<keystore_type> The type of keystore. For nCipher, this must be set to nCipher . sword. 
<keystore_name> The name you specified when you created the keystore. In this sample 


configuration, the name is AMstore. jks. 


<keystore_pwd> When you use module-protected keys, the keystore password must be 
null. For example: 


com.novell.nidp.extern.signing.keystorePwd= 


<key_alias> The alias you created for the key when you created the key. In this 
sample configuration, the name is 0d93. 


<key_pwd> When you use module-protected keys, the key password must be null. 
For example: 


com.novell.nidp.extern.signing.keyPwd= 


6 To restart Tomcat, enter one of the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 


7 Continue with “Verifying the Use of the nCipher Key Pair” on page 925. 
Configuring a Windows Identity Server for the Certificate 


1 At Identity Server, log in as the Windows administrator. 
2 Add the nfast JAR files to the classpath. 


Because Identity Server runs as a Tomcat service, the following steps explain how to modify the 
classpath for Tomcat. 


2a Run the tomcat7w. exe utility located in the following directory: 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat\bin 

2b Click the Java tab. 

2c In the Java Classpath text box add the following to the end of the path: 


"'C:\nfast\java\classes\jcetools.jar;C:\nfast\java\classes\jutils.jar;C:\n 
fast\java\classes\keysafe. jar;C:\nfast\java\classes\kmcsp.jar;C:\nfast\jav 
a\classes\kmjava.jar;C:\nfast\java\classes\nfjava.jar;C:\nfast\java\classe 
s\rsaprivenc.jar;C:\nfast\java\classes\spp.jar" 


2d Save your changes. 
3 Add the netHSM certificate configuration lines to the tomcat7.conf file: 
3a Run the tomcat7w.exe utility located in the following directory: 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat\bin 
3b Click the Java tab. 
3c In the Java Options text box, add the following as three separate lines: 
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-Dcom.novell.nidp.extern.config.file=C : \PROGRA~1\Novell\Tomcat\webapps 
\nidp\WEB-INF\classes\externKeystore. properties 

-Dprotect=module 

-DignorePassphrase=true 


The first line specifies the location of the properties file. For readability, it has been wrapped 
and indented. Remove the extra white space when creating the entry in the file. You can 
specify another location. 


The second line is required only if you want the keystore to be module protected rather than 
card protected. 


4 Configure the externKeystore.properties file to use the nCipher key and keystore: 
4a In a text editor, create an externKeystore. properties file in the following directory: 


Windows Server 2012: \Program Files (x86)\Novell\Tomcat\webapps\nidp \WEB- 
INF\classes 


If you specified a different location for this file in Step 3, use that location. 
4b Add the following lines: 


com.novell.nidp.extern.signing.providerClass=com.ncipher.provider .km.nCiph 
erkM 
com.novell.nidp.extern.signing.providerName=nCipher kM 
com.novell.nidp.extern.signing.keystoreType=nCipher .sworld 
com.novell.nidp.extern.signing.keystoreName=C:\\Program Files\\Novell\\ 
devman\\jcc\\certs\\idp\\AMstore. jks 
com.novell.nidp.extern. signing. keystorePwd=mypwd 
com.novell.nidp.extern.signing.alias=od93 
com.novell.nidp.extern.signing.keyPwd=mypwd 


The com.novell.nidp.extern.signing.keystoreName line is wrapped and indented for 
readability. All extra white space needs to be removed in the file entry. The double slashes 
in the path are required. 


Enter your values for the following variables: 


Variable Value 


<provider_class> The name of the providerClass. For nCipher, this must be set to 
com.ncipher.provider .km.nCipherkM. 


<provider_name> The name of the provider. For nCipher, this must be set to nCipherk™. 
<keystore_type> The type of keystore. For nCipher, this must be set to nCipher . sword. 
<keystore_name> The name you specified when you created the keystore. In this sample 


configuration, the name is AMstore. jks. 


<keystore_pwd> When using module-protected keys, the keystore password must be 
null. For example: 


com.novell.nidp.extern.signing.keystorePwd= 


<key_alias> The alias you created for the key when you created the key. In this 
sample configuration, the name is 0d93. 


<key_pwd> When using module-protected keys, the key password must be null. For 
example: 


com.novell.nidp.extern.signing.keyPwd= 


5 To restart Tomcat, enter the following commands: 
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net stop Tomcat7 
net start Tomcat7 


6 Continue with “Verifying the Use of the nCipher Key Pair” on page 925. 


Verifying the Use of the nCipher Key Pair 


After you have configured Identity Server to use the nCipher key pair and have restarted Tomcat, the 
metadata of Identity Server indicates that the nCipher key pair is being used for the signing certificate. 


1 Ina browser, enter the following URL: 
http://<DNS_name>:8080/nidp/idff/metadata 


Replace <DNS_name> with the DNS name of your Identity Server. 

2 Search for the following string: 
<md:KeyDescriptor use="Signing"> 

3 Copy the certificate text between the <ds:X509Certificate> and the </ds:X509Certificate> 
tags 

4 Paste the text into a text editor. 

5 Delete the <ds:X509Certificate> tag and replace it with the following text: 


7 Save the file as a text file with a .cer extension. 
8 Open the file in Internet Explorer. 
9 View the certificate details. 


If Identity Server is using the nCipher signing certificate, the certificate is issued by your CA and 
the name the certificate is issued to is the name you specified for the certificate. 


If Identity Server is using the Access Manager certificate, the certificate is issued by the 
Organizational CA and the certificate name is test -signing. For troubleshooting information, 
see “Troubleshooting the netHSM Configuration” on page 925. 


Troubleshooting the netHSM Configuration 
To discover potential configuration errors: 


1 Verify that you have not enabled the data encryption of resource IDs. There is a known issue 
with this feature and the Apache libraries in a multi-provider environment. Because of this issue, 
netHSM is not compatible with encrypting the resource IDs. 


1a Click Devices > Identity Servers > Edit > Liberty > Web Service Provider. 


1b Click a profile, then check the setting for the Have Discovery Encrypt This Service’s 
Resource Ids option. 


1c If the option is selected, deselect it, then click OK. 
1d Verify that all profiles have been configured so that they do not encrypt the resource IDs. 
2 View the nfast log files: 
Linux: /opt/nfast/log 
Windows: C:\nfast\log 
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When there is a port conflict, logfile contains entries similar to the following: 


nFast server: Notice: Using tcp socket local:9000 
nFast server: Fatal error during startup: Operating system call failed: bind 
tcp socket, Address already in use 


For information about how to change the port, see Step 6 on page 915. For other errors, consult 
the netHSM documentation. 


3 (Linux only) If the novlwww user does not have rights to the cmdadp.1log and cmdadp-debug. log 
files, Identity Server is halted because it cannot read the keystore. The Health page of Identity 
Server displays the following error: 


The following error occurred during Identity Server configuration. Unable to 
read keystore: /opt/novell/devman/jcc/certs/idp/AMstore45. jks 


To correct the error: 
3a View the rights for the nfast log files with the following command: 


11 /opt/nfast/log 
Your listing should look similar to the following: 


-rw-r--r-- 1 novlwww nfast © Apr 11 11:50 cmdadp-debug.1log 
-rw-r--r-- 1 novlww nfast 134 Apr 11 11:50 cmdadp.log 


-rW-r----- 1 root nfast 43 Apr 11 11:49 debug 
-rW-r----- 1 nfast nfast 5 Apr 11 11:49 hardserver.pid 
-rW-r----- 1 nfast nfast 3057 Apr 11 11:50 logfile 


If novlwww is not listed as the owner of the cmdadp . log and cmdadp -debug . log files, 
continue with Step 3b. 


If novlwww is listed as the owner of the files with rw permissions, log file ownership is not the 
source of your problem. Continue with Step 4. 


3b Stop Tomcat with one of the following commands: 
/etc/init.d/novell-idp stop 
rcnovell-idp stop 

3c Stop nfast with the following command: 
/opt/nfast/sbin/init.d-nfast stop 

3d Delete all the log files in the /opt/nfast/log directory. 

3e Start nfast with the following command: 
/opt/nfast/sbin/init.d-nfast start 

3f Start Tomcat with one of the following commands: 
/etc/init.d/novell-idp start 
rcnovell-idp start 

3g Wait a minute, then list the files in the /opt/nfast/log directory. 
The nfast client creates the log files and assigns the correct owners and rights. 

4 Enable Identity Server logging and view the catalina. out file. 

4a Click Devices > Identity Servers > Edit > Logging. 

4b Configure the following options: 
File Logging: Specify enabled. 
Echo to Console: Select this option. 
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Component File Logger Levels: Set Application to debug. 
4c Click OK, then update Identity Server. 


4d Delete the current catalina. out file in the /var/opt/novell/nam/logs/idp/tomcat 
directory. 


4e Restart Tomcat by entering one the following commands: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 


4f To tail the catalina. out file, enter the following command: 
tail -f /var/opt/novell/nam/logs/idp/tomcat/catalina.out 


4g Search for a list of providers. When nCipher is working, the file contains entries similar to 
the following nCipher entries: 


Security Providers: 
SUN: 1.42 
SUN (DSA key/parameter generation; DSA signing; SHA-2, MD5 digests; 
SecureRandom; X.509 certificates; JKS keystore; PKIX CertPathValidator; 
PKIX CertPathBuilder; LDAP, Collection CertStores) 
SunJSSE: 1.42 
Sun JSSE provider(implements RSA Signatures, PKCS12, SunX509 key/ 
trust factories, SSLv3, TLSv1) 
SunRsaSign: 1.42 
SUN's provider for RSA signatures 
SunJCE: 1.42 
SunJCE Provider (implements DES, Triple DES, AES, Blowfish, PBE, 
Diffie-Hellman, HMAC-MD5, HMAC-SHA1) 
SunJGSS: 1.0 
Sun (Kerberos v5) 
nCipherRSAPrivateEncrypt: 1.008004 
RSA private key encrypt handling provider 
nCipherKM: 1.008004 
nCipher Secure Key Management 
BC: 1.28 
BouncyCastle Security Provider v1.28 
SAML: 1.0 
SAML SASL Mechanism 


4h (Conditional) If the catalina. out file does not contain any entries for providers, check for 
the following errors: 


e Check the Health of Identity Server. If the status is red, use the error message to 
resolve the issue. 


+ Ensure that the novlwww user has read rights to the keystore. 


¢ Verify that the externKeystore.properties file has all the required lines with valid 
values. See Step 5 on page 922. 


¢ Verify that the tomcat7.conf file is configured correctly. See Step 4 on page 922. 
5 Enable netHSM logging. 


This logging feature is very verbose. It should be turned on only while you are debugging a 
problem. If it is left on, your machine can quickly run out of disk space. 


5a To the tomcat7.conf file in the /opt/novell/nam/idp/conf directory, add the following 
line: 


JAVA_OPTS="${JAVA_OPTS} -DJCECSP_DEBUG=255 -DJCECSP_DEBUGFILE=/opt/novell/ 
nam/idp/logs/nCipher_jcecsp.debug" 
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10.6 


10.6.1 


5b Restart Tomcat by entering one of the following command: 
/etc/init.d/novell-idp restart 
rcnovell-idp restart 


5c Look for clues in the nCipher_jcecsp. debug file. 


Enabling Secure Cookies 


Access Gateway and Embedded Service Provider of Access Gateway both use session cookies in 
their communication with the browser. The following sections explain how to protect these cookies 
from being intercepted by hackers. 


¢ Section 10.6.1, “Securing the Embedded Service Provider Session Cookie on Access Gateway,” 
on page 928 
¢ Section 10.6.2, “Securing the Proxy Session Cookie,” on page 929 


For more information about making cookies secure, see the following documents: 


¢ Secure attribute for cookies in RFC 2965 (http://www.faqs.org/rfcs/rfc2965.html) 
¢ HTTP-only cookies (http://msdn.microsoft.com/en-us/library/ms533046.aspx) 


Securing the Embedded Service Provider Session Cookie 
on Access Gateway 


An attacker can spoof a non-secure browser into sending a JSESSION cookie that contains a valid 
user session. This might happen because Access Gateway communicates with its ESP on port 9009, 
which is a non-secure connection. Because ESP does not know whether Access Gateway is using 
SSL to communicate with the browsers, ESP does not mark the JSESSION cookie as secure when it 
creates the cookie. Access Gateway receives the Set-Cookie header from ESP and passes it to the 
browser as a non-secure clear-text cookie. If an attacker spoofs the domain of Access Gateway, the 
browser sends the non-secure JSESSION cookie over a non-secure channel where the cookie might 
be sniffed. 


To stop this, you must first configure Access Gateway to use SSL. See Section 17.5, “Configuring 
SSL Communication with Browsers and Access Gateway,” on page 993. 


After you have SSL configured, you must configure Tomcat to secure the cookie. 


1 Log in to Access Gateway server as an admin user. 
2 Change to the Tomcat configuration directory. 
Linux: /opt/novell/nam/mag/conf/ 
Windows: /Program Files/Novell/Tomcat/conf 
3 Ina text editor, open the server.xml] file. 
4 Search for the connector on port 9009. 
5 Add the following parameter within the Connector element: 


secure="true" 


6 Save the server.xml file. 
7 Enter one of the following commands to restart Tomcat: 


Linux: /etc/init.d/novell-mag restart OR rcnovell-mag restart 
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10.6.2 


10.6.2.1 


10.6.2.2 


Windows: Use the following commands: 
net stop apache2.2 
net start apache2.2 
Preventing Automatically Changing Session ID 

1. Go to Devices > Access Gateway > Edit > Reverse Proxy / Authentication > ESP Global 
Options. 

2. Set RENAME_SESSIONID to false. By default, this is set to true. 

3. Restart Tomcat on each Identity Server in the cluster. 


Securing the Proxy Session Cookie 


The proxy session cookies store authentication information and other information in temporary 
memory that is transferred between the browser and the proxy. These cookies are deleted when the 
browser is closed. However if these cookies are sent through a non-secure channel, hackers might 
intercept the cookies and impersonate a user on websites. To stop this, you can use the following 
configuration options: 


¢ Section 10.6.2.1, “Setting an Authentication Cookie with a Secure Keyword for HTTP,” on 
page 929 


¢ Section 10.6.2.2, “Preventing Cross-Site Scripting Vulnerabilities,” on page 929 


Setting an Authentication Cookie with a Secure Keyword for HTTP 


You can configure Access Gateway to force the HTTP services to have the authentication cookie set 
with the keyword secure. 


To enable this option, perform the following steps: 
1 Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication. 


2 Select Enable Secure Cookies, then click OK twice. 
3 Update Access Gateway. 


This option is used to secure the cookie when Access Gateway is placed behind an SSL accelerator, 
such as the Cisco SSL accelerator, and Access Gateway is configured to communicate by using only 
HTTP. 


Preventing Cross-Site Scripting Vulnerabilities 


Cross-site scripting vulnerabilities in web browsers allow malicious sites to grab cookies from a 
vulnerable site. The goal of such attacks might be to perform session fixation or to impersonate a 
valid user. You can configure Access Gateway to set its authentication cookie with the Httponly 
keyword to prevent scripts from accessing the cookie. 


To enable this option, perform the following steps: 


1 Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication. 
2 Select Force HTTP-Only Cookies, then click OK > OK. 
3 Update Access Gateway. 
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10.7.1 


Preventing Cross-site Scripting Attacks 


By default, Access Manager does extensive checks to prevent Cross-site Scripting (XSS) attacks. 
However, Access Manager does not validate a JSP file if you have customized it. If you modify JSP 
files to customize the login, logout, error pages, and so forth, you must sanitize the JSP file to prevent 
XSS attacks. 


You need to perform either one of the following options to sanitize the customized JSP file: 


+ “Option 1: HTML Escaping” on page 930 
+ “Option 2: Filtering” on page 931 


Option 1: HTML Escaping 


Perform the following XSS checks for the customized JSP file to protect it from possible XSS attacks. 
For more information about XSS prevention techniques, see XSS (Cross Site Scripting) Prevention 
Cheat Sheet. 


Perform the following steps: 


1 Verify if the org.apache.commons.lang.StringEscapeUtils class is available in the JSP file. 


For example, the following import statement should be available in the import section of the JSP 
file: 


<%@ page import="org.apache.commons.lang.StringEscapeUtils"%> 
2 Verify if all URL query parameter values are sanitized. 


The following code snippet sample shows how URL query parameter values (uname and target) 
can be sanitized: 


<%//Fetch the values from URL query parametersString target = (String) 
request.getAttribute("target");String uname = (String) 


request.getAttribute("username"); String sanitizedUName = ""; if (uname != 
null){//Sanitize the value assigned to uname sanitizedUName = 
StringEscapeUtils.escapeHtml(uname); } String sanitizedTarget = ""; if (target 


!= null){ //Sanitize the value assigned to target query param sanitizedTarget = 
StringEscapeUtils.escapeHtml(target) ; }%> 


3 Add double quotes ("") in value attribute (or any attribute that is dynamically assigned) for any 
HTML element that get assigned with above URL query param value. 


<!-- The last 2 double quotes are mandatory to prevent XSS attacks --><input 
type="text" class="smalltext" name="Ecom_User_ID" size="30" 
value="<%=sanitizedUName%>">...... <!-- The last 2 double quotes are mandatory 


to prevent XSS attacks --><input type="hidden" name="target" 
value="<%=sanitizedTarget%>"> 


4 Restart the component whose JSP file you have modified. For example, if you modify Identity 
Server's JSP file, restart Identity Server by running the following command: 


Linux: sh /etc/init.d/novell-idp restart 
Windows: net start Tomcat7 


930 Securing Access Manager 


10.7.2 Option 2: Filtering 


By deafult, the XSS detection filter is enabled in Identity provider's web. xm1 file: 


¢ Linux: /opt/novell/nam/idp/webapps/nidp/WEB- INF 
+ Windows: C:\Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- INF 


The filter is as follows: 


<filter> 
<filter -name>xSSDetectionFilter</filter -name> 
<filter- 
class>com.novell.nidp.servlets.filters.xss.XSSDetectionFilter</filter-class> 
<description>This filter is used to detect XSS attacks in NIDS</ 
description> 
<init-param> 
<param-name>active</param-name> 
<param-value>True</param-value> 
</init-param> 
<init-param> 
<param-name>level</param-name> 
<param-value>SCRIPT_TAGS</param-value> 
</init-param> 
<init-param> 
<param-name>exclude</param-name> 
<param-value>soap,wstrust,metadata, oauth</param-value> 
</init-param> 
</filter> 


To disable it, set the <param-value> True to False as follows: 


<init-param> 
<param-name>active</param-name> 
<param-value>False</param-value> 
</init-param> 


To exclude it from a specific request, add a URL string from that request in the <param- 
name>exclude</param-name> tag that contains the default excluded request path name. 


For example: If wsfed request fails due to some reason, add wsfed in the exclude list. Now, Identity 
Provider will not filter wsfed specific requests. 


The exclude init-param is as follows: 


<init-param> 

<param-name>exclude</param-name> 

<param-value>soap, wstrust, metadata, oauth, wsfed</param-value> 
</init-param> 


NOTE: It is recommended to use the above option as it overrides the following approach: 


This approach might have a minor performance impact due to the checks it performs. If you perform 
HTML escaping in customized JSP pages, you do not need to perform this additional filtering. 


Perform the followings steps to sanitize Identity Server's customized JSP file: 


1 The eMFrame_xss. jar file is located at: 
Linux: /opt/novell/nids/1ib/webapp/nidp/WEB-INF/1ib 
Windows: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB-INF\1ib 


Securing Access Manager 931 


This library prevents XSS based attacks. 
2 Add a filter in the web. xm1 file located at: 
Linux: /opt/novell/nam/idp/webapps/nidp/WEB- INF 
Windows: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- INF 


<filter><filter -name>XSS</filter -name><display-name>XSS</display- 
name><description>Filters XSS injections.</description> <filter- 
class>com.novell.emframe.fw.filter.CrossScriptingFilter</filter-class></ 
filter> <filter -mapping><filter -name>XxSS</filter -name><url-pattern>/*</url- 
pattern></filter -mapping> 


3 Restart Identity Server by running the following command: 
Linux: /etc/init.d/novell-idp restart 


Windows: net start Tomcat7 
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Setting Up Advanced Session 
Assurance 


With the introduction of risk-based authentication mechanisms combined with strong authentication 
methods, manipulating user credentials to gain unauthorized access has become very difficult. Many 
web applications use cookies to manage the user sessions. Numerous basic security measures are 
available to secure the session cookie. However, cookies are susceptible to replay attacks. Session 
timeouts and IP address validations can minimize the chances of replay attacks. But, chances of 
misusing a session cookie to gain unauthorized access to an active session still exist. 


Advanced Session Assurance enables you to prevent session replay attacks by adding an additional 
layer of security to your sessions. When a session is established, Access Manager creates a unique 
fingerprint of the device from which the session is established. During the session, at a configurable 

time interval, Access Manager validates the session to ensure that the fingerprint matches with that of 
the device it originated from. 


Access Manager also generates a new ID for the session at a specified time interval. If the fingerprint 
or the session ID does not match, Access Manager logs the user out and invalidates the session. 


Advanced Session Assurance provides three levels of protection as follows: 


¢ Session Renewal: A new ID for the active session is generated at the specified interval. Even 
after enabling fingerprinting, if intruders steal the session ID, they cannot hijack the session as 
the ID keeps changing after the specified time. In a fresh install, this is enabled for both Identity 
Server and Access Gateway by default. However, it is disabled for both Identity Server and 
Access Gateway in an upgraded setup. 


+ Device Fingerprinting: A fingerprint is created by using the parameters fetched from the user's 
device such as hardware parameters and screen resolution. 


¢ Server-side Fingerprinting: A fingerprint is created by using the parameters fetched at the 
server-side using request parameters such as http headers or IP address. 


Access Manager supports the following parameters in Advanced Session Assurance validations for 
Identity Server and Access Gateways sessions: 


Table 11-1 Advanced Session Assurance Parameters 


Parameter Description 


Request Parameters: 


Client IP Fetches the IP address of the client. 


Request Header Set Fetches the user-agent from the request headers of the incoming request. 
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Parameter 


Device Parameters: 


Description 


Hardware Parameters 


Fetches the following details about the user’s device: 


+ Touch support 

+ Maximum number of supported touch points 
+ CPU architecture (32 or 64-bit processor) 

+ Color depth 

+ Type (mobile, desktop, or iPad) 


Language Set 


Fetches language preferences of the user's device. 


Screen Resolution 


Fetches width and height of the user's browser and screen. 


Time Zone Offset 


Fetches time zone of the user's device. 


Operating System 


Fetches name and version of the operating system on the user’s device. 


User Agent 


Fetches the following details about the browser on the user’s device: 


+ Version 
+ Name 
+ Platform of the browser 


+ Number of logical processors cores available to the browser 


HTML5 Capabilities 
(Performance 
Intensive) 


Fetches the information about HTML 5 capabilities that are supported by the 
browser. 


System Fonts 


Fetches the information about fonts supported and unsupported by the user's 


(Performance browser. 

Intensive) 

WebGL Metadata Fetches information about the GPU (Graphics Processing Unit), the identity of the 
(Performance browser, WebGL properties, and characteristics supported by the browser. 
Intensive) 


WebGL (Web Graphics Library) is a JavaScript API for rendering interactive 3D 
computer graphics and 2D graphics within any compatible web browser without 
using plug-ins. 


This section includes the following topics: 


¢ “Enabling Advanced Session Assurance at the Cluster Level” on page 935 


¢ “Enabling Advanced Session Assurance at the Proxy Service Resource Level” on page 935 


¢ “Setting Up Session Validation and Renewal Interval” on page 936 


¢ “Modifying Parameters Settings” on page 937 


¢ “Disabling Advanced Session Assurance” on page 937 


+ “An Example Configuration” on page 940 


¢ Section 30.10, “Troubleshooting Advanced Session Assurance,” on page 1249 
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Enabling Advanced Session Assurance at the Cluster 
Level 


Identity Server: By default, in a fresh installation, both device fingerprinting-based and server-side 
fingerprinting-based validations are enabled for all clusters. 


Access Gateway: By default, in a fresh installation, device fingerprinting-based validation is disabled 
and server-side fingerprinting-based validation is enabled for all clusters. 


To enable device fingerprinting-based validation for Access Gateway, you must enable it at the proxy 
service resource level. See “Enabling Advanced Session Assurance at the Proxy Service Resource 
Level” on page 935. 


NOTE: Advanced Session Assurance is disabled by default for Identity Server and Access Gateway 
in an upgraded setup. You must upgrade all nodes in the clusters of Identity Server and Access 
Gateway to version 4.3 before enabling Advance Session Assurance.” 


For Access Gateway clusters and proxy services, you should enable Advanced Session Assurance 
only if needed. See “Best Practices for Enabling Advanced Session Assurance at the Proxy Service 
Resource Level” on page 936. 


Perform the following steps to enable Advanced Session Assurance at the cluster level: 


1 Click Security > Advanced Session Assurance. 


2 In Cluster Level Configurations, select Identity Server clusters or Access Gateway clusters for 
which you want to enable Advanced Session Assurance. 


Enabling Advanced Session Assurance at the Proxy 
Service Resource Level 


For Access Gateway, you can disable or enable device fingerprinting-based validation at the proxy 
service level at the respective configuration pages or at the Advanced Session Assurance page. 


Perform anyone of the following procedures to enable Advanced Session Assurance at the proxy 
service level: 


At the respective configuration page: 


1 Click Devices > Access Gateway > Edit > [name of reverse proxy] > [name of proxy service]. 


2 Select Enable Advanced Session Assurance. 
At the Advanced Session Assurance page: 


1 Click Security > Advanced Session Assurance. 


2 Click Proxy Service Settings, select the proxy service for which you want to enable the device 
fingerprinting-based validation. 
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Best Practices for Enabling Advanced Session Assurance 
at the Proxy Service Resource Level 


Before enabling the Advanced Session Assurance for your applications, understand how this works. 
See Table 11-1, “Advanced Session Assurance Parameters,” on page 933. 


If the application is a single page application or runs with browser plug-ins, consider the following 
scenarios: 


+ As the cookie gets renewed on the browser at the specified interval, ensure that your application 
picks up the updated cookie and sends it with every request. 


+ When you enable server-side fingerprinting, ensure that your application sends the same user- 
agent header over the entire session. 


For example, assume SharePoint is protected by Access Gateway. When you try to open any 
application on SharePoint such as an Microsoft Word document, the user agent value changes 
when the document opens. 


The session validation in such scenarios may fail. However, the session is valid. To prevent this, 
you can exclude the proxy service associated with SharePoint from the session validation. See 
“Disabling Advanced Session Assurance for Access Gateway Proxy Services” on page 939>. 


¢ Client-side fingerprinting includes many client-side parameters. Ensure that the enabled 
parameters do not change during the session. 


Setting Up Session Validation and Renewal Interval 


Access Manager enables you to set the interval for session validation and session ID renewal for 
Identity Server and Access Gateway. You can specify different values for Identity Server and Access 
Gateway. 


Perform the following steps to set up session validation and renewal interval: 


1 Click Security > Advanced Session Assurance. 


2 Under Session Validation and Renewal Interval, specify the interval for session validation. 
Access Manager also generates a new ID for the session after the same interval. 


IMPORTANT: Users may not go to Identity Server or Access Gateway Embedded Service Provider 
(ESP) very regularly. So, in the following scenarios, this interval may not work and the session will be 
renewed with the next request after the interval: 


¢ Federated setups: When a user logs into Identity Server, Access Manager generates an 
assertion to the service provider (SP). After that the SP owns the user session and session 
assurance renewal will not work till the SP periodically comes back to Identity Server to renew 
the session assurance. 


+ Access Gateway setups: When a user accesses and logs into a protected resource, that user 
usually does not return to ESP or Identity Server until the session timeout has exceeded or 
another authentication request comes to Identity Server. For example, if the default contract 
timeout is set to 60 min, the user may not come back to Identity Server or ESP approximately for 
40 min. Even if the session renewal is set to 1 min (default), the user may not come back to 
Identity Server and renew the session info. 
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Modifying Parameters Settings 


1 Click Security > Advanced Session Assurance. 
2 Click Parameters Setting. 


3 Select the parameters for Identity Server and Access Gateway that you want to include in 
session validations. 


For more information about parameters, see Table 11-1, “Advanced Session Assurance 
Parameters,” on page 933. 


Disabling Advanced Session Assurance 


If any critical issue happens, you can disable Advanced Session Assurance for the specific URLs and 
user-agents. You need to add the URL or user agent to the exclude list of each Identity server cluster 
and ESP cluster. For both URL and user agent, you can either specify strings or regular expression 
as input. 


NOTE: You can also deselect the cluster to disable Advanced Session Assurance. However, 
disabling Advanced Session Assurance at the cluster level disables it for the entire Access Manager 
setup. 


¢ “Disabling Advanced Session Assurance for Identity Server” on page 937 
¢ “Disabling Advanced Session Assurance for Access Gateway ESP” on page 938 


+ “Disabling Advanced Session Assurance for Access Gateway Proxy Services” on page 939 


Disabling Advanced Session Assurance for Identity Server 


1 Click Devices > Identity Servers > Edit > Options > New. 
2 Set the following properties: 
Multiple inputs must be separated by comma. 


Property Type Property Value 
SESSION ASSURANCE USER AGENT Specify the user-agent string for that you want to 
EXCLUDE LIST disable the session validation. 


For example, you can specify Android to exclude 
Android devices (version 4.x). Examples of user 
agent sent by Android devices: 


User-Agent: Mozilla/5.0 (Linux; Android 4.4.3; 
KFTHWI Build/KTU84M) AppleWebKit/537.36 
(KHTML, like Gecko) Silk/44.1.54 like Chrome/ 
44.0.2403.63 Safari/537.36 


You can specify MSIE to exclude Internet Explorer 
10.x. Examples of user agents sent by Internet 
Explorer: 


Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 


6.1; WOW64; Trident/6.0) 
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Property Type Property Value 


SESSION ASSURANCE USER AGENT REGEX Specify the user-agent REGEX for that you want to 
EXCLUDE LIST disable the session validation. 


For example, you can specify Android 4\. to 
exclude Android devices (version 4.x). Examples 
of user agent sent by Android devices: 


User-Agent: Mozilla/5.0 (Linux; Android 4.4.3; 
KFTHWI Build/KTU84M) AppleWebkKit/537.36 
(KHTML, like Gecko) Silk/44.1.54 like Chrome/ 
44.0.2403.63 Safari/537.36 


You can specify MSIE 10\. to exclude Internet 
Explorer 10.x. Examples of user agents sent by 
Internet Explorer: 


Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 
6.1; WOW64; Trident/6.0) 


SESSION ASSURANCE URL EXCLUDE LIST Specify the URL for that you want to disable the 
session validation. 


For example, if you want to exclude any URL 
based on any string. Let assume the URL is http:// 
www.xyz.com/hr/main, specify /hr/ to verify 
whether the URL contains /hr/. If yes, then the URL 
will be excluded from session validation. 


SESSION ASSURANCE URL REGEX EXCLUDE Specify the URL REGEX for that you want to 
LIST disable the session validation. 


For example, let assume the URL is http:// 
www.xyz.com/hr/main, specify www. xyz.com/hr/ 
(. )* to verify whether the URL contains /hr/. If 
yes, then the URL will be excluded from session 


validation. 
SESSION ASSURANCE IDC COOKIE Specify the time in second till which Identity Server 
GRACEPERIOD will accept the old session ID, after issuing a new 


ID. The default value is 15 second. 


Disabling Advanced Session Assurance for Access Gateway ESP 
1 Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication > ESP Global 
Options. 
2 Add the following options in the ESP Global Options list: 
Multiple inputs must be separated by comma. 


ESP Global Options Description 
SESSION_ASSURANCE_USER Specify the user-agent string for that you want to 
AGENT_EXCLUDE_LIST disable the session validation. 


For example, if you want to exclude android 
devices, add the following: 


SESSION_ASSURANCE_USER_AGENT_EXCLUDE_LI 
ST Android, Chrome 
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ESP Global Options 


SESSION_ASSURANCE_USER_AGENT_REGE 
X_EXCLUDE_LIST 


Description 


Specify the user-agent REGEX for that you want to 
disable the session validation. 


For example, if you want to exclude android 
devices with version 4 and later, add the following: 


SESSTON_ASSURANCE_USER_AGENT_REGEX_EXCL 
UDE_LIST Android 4\.,Chrome 


SESSION_ASSURANCE_URL_EXCLUDE_LIST Specify the URL for that you want to disable the 


session validation. 


For example, if you want to exclude any URL 
based on any string. Let assume the URL is http:// 
www.xyz.com/hr/main, the following entry will 
verify whether the URL contains /hr/. If yes, then 
the URL will be excluded from session validation: 


SESSION_ASSURANCE_URL_EXCLUDE_LIST /hr/ 


SESSION_ASSURANCE_URL_REGEX_EXCLU 
DE_LIST 


Specify the URL REGEX for that you want to 
disable the session validation. 


For example, if you want to exclude any URL 
based on any string. Let assume the URL is http:// 
www.xyz.com/hr/main, the following entry will 
verify whether the URL contains /hr/. If yes, then 
the URL will be excluded from session validation: 


SESSTON_ASSURANCE_URL_REGEX_EXCLUDE_LIS 
T www.xyz.com/hr/(.)* 


SESSION_ASSURANCE_IDC_COOKIE_GRACE 
PERIOD 


Specify the time in second till which Identity Server 
will accept the old session ID, after issuing a new 
ID. The default value is 15 second. 


Disabling Advanced Session Assurance for Access Gateway Proxy Services 


When Advanced Session Assurance is enabled at the cluster level for a proxy service, server-side 
fingerprinting and session ID Session Assurance are enabled. You can disable and re-enable it by 
using advanced options. 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> Advanced Options. 
2 Add the following options on the need basis: 


Option Description 


NAGHostOptions DisablelIDC on This disables Advance Session Assurance for small lived session 


IDs. 


Set to off to enable Advance Session Assurance for session ID. 


NAGHostOptions DisableSFP on This disables server-side fingerprinting Session Assurance. 


Set to off to enable server-side fingerprinting Session Assurance. 


3 Save your changes and update Access Gateway. 
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An Example Configuration 


Let assume an organization has a Human Resources application and a Payroll application. Both 
applications contain highly confidential data of its employees. These applications are protected by 
Access Gateway. 


The organization wants to prevent session hijacking for these applications. This can be achieved by 
enabling device fingerprinting-based session validations for proxy services tied to these applications. 


Configuration Steps: 


1 Click Security > Advanced Session Assurance. 


2 In Enable Advanced Session Assurance for Clusters, select the required Identity Server 
clusters and Access Gateway clusters for which you want to enable Advanced Session 
Assurance. 


3 Specify Session Validation and Renewal Interval. 

For more information, see “Setting Up Session Validation and Renewal Interval” on page 936. 
4 Select parameters that you want to include in the session validation. 

For more information about parameters, see Table 11-1 on page 933. 


5 Click Proxy Service Settings and select the proxy services tied up with the Human resources 
and Payroll applications. 


6 Click OK. 
7 Update Access Gateway. 
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Understanding Access Manager 
Certificates 


Access Manager allows you to manage centrally stored certificates used for digital signatures and 
data encryption. eDirectory resides on Administration Console and is the main certificate store for all 
of the Access Manager components. If you use a Novell Certificate Server, you can create certificates 
there and import them into Access Manager. 


By default, all Access Manager components (Identity Server and Access Gateway) trust the local 
Access Manager certificate authority (CA). However, if Identity Server is configured to use an SSL 
certificate signed externally, the trust store of the Embedded Service Provider for each component 
must be configured to trust this new CA. 


Certificate management commands issued from a secondary Administration Console can work only if 
the primary console is also running properly. Other commands can work independently of the primary 
console. 


You can create and distribute certificates to the following components: 


¢ Identity Server: Uses certificates and trust stores to provide secure authentication to Identity 
Server and enable encrypted content from Identity Server portal via HTTPS. Certificates also 
provide secure communications between trusted Identity Servers and user stores. 


Liberty and SAML 2.0 protocol messages that are exchanged between identity and service 
providers often need to be digitally signed. Identity Server uses the signing certificate included 
with the metadata of a trusted provider to validate signed messages from the trusted provider. 
For protocol messages to be exchanged between providers through SSL, each provider must 
trust the CA of the other provider. You must import the public key of the CA used by the other 
provider. 


Identity Server also has a trust store for OCSP (Online Certificate Status Protocol) certificates, 
which is used to check the revocation status of a certificate. 


+ Access Gateway: Uses server certificates and trusted roots to protect Web servers, provide 
single sign-on, and enable the product’s data confidentiality features, such as encryption. They 
are used for background communication with Identity Server and policy engine and to establish 
trust between Identity Server and Access Gateway. 


To ensure the validity of X.509 certificates, Access Manager supports both Certificate Revocation 
Lists (CRLs) and Online Certificate Status Protocol (OCSP) methods of verification. 


When X509 authentication is configured as the authentication contract, it works even after you revoke 
the certificate for the X509 mutual authentication. When you access the nidp login page from the 
client browser and select the revoked certificate, browser does not throw an error message telling 
that the certificate has been revoked. You can either issue a CRL or wait until the next CRL issuance 
date. The revoked certificates will work until the next CRL issuance date. 


If you do not want to wait and issue a CRL now, perform the following steps: 


1 Navigate to Roles and Tasks > NetIQ Certificate Server > Configure Certificate Authority > 
CRL. 


2 Click CRL. 
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3 Under Next CRL Issuance, click Issue Now. 
4 Click OK. 
5 Restart Identity Server. 


Access Manager stores the certificates that a device has been configured to use in trust stores and 
keystores. This section describes the following certificate features: 

¢ Section 12.1, “Process Flow,” on page 942 

¢ Section 12.2, “Access Manager Trust Stores,” on page 943 

¢ Section 12.3, “Access Manager Keystores,” on page 944 


Process Flow 


You can install and distribute certificates to the Access Manager components and configure how the 
components use certificates. This includes central storage, distribution, and expired certificate 
renewal. Figure 12-1 illustrates the primary administrative actions for certificate management in 
Access Manager: 


Figure 12-1 Certificate Management 
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1. Generate a certificate signing request (CSR). See Section 13.4, “Generating a Certificate 
Signing Request,” on page 952. 


2. Send the CSR to the external certificate authority (CA) for signing. 


A CA is a third-party or network authority that issues and manages security credentials and 
public keys for message encryption. The CA's certificate is held in the configuration store of the 
computers that trust the CA. 


3. Import the signed certificate and CA chain into the configuration store. See “Importing Public Key 
Certificates (Trusted Roots)” on page 971. 


4. Assign certificates to devices. See “Assigning Certificates to Access Manager Devices” on 
page 965. 


If you are unfamiliar with public key cryptography concepts, see “Public Key Cryptography Basics” in 
the Novell Certificate Server 3.1.1 Guide. 
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Access Manager Trust Stores 


A trust store contains trusted roots, which are public certificates of known, trusted certificate 
authorities. Access Manager creates the trust stores listed below for the devices that it manages. The 
trust stores are created when you import a device into Administration Console. If you have not 
imported a particular device type, the trust store for that device type does not exist. If you have 
imported multiple devices of the same type, Administration Console creates an instance of the trust 
store for each device. 


When a certificate has been created by a root CA, the trust store needs to contain only the public 
certificate of the CA. However, some certificates are created by an intermediate CA, which has been 
issued by a root CA. When intermediate CAs are involved, all the public certificates of the CAs in the 
chain need to be included in the trust store. 


Administration Console creates a trust store in the file system of the device that is assigned to the 
trust store. 


¢ Linux: /opt/novell/devman/jcc/certs/<device> 


+ Windows Server 2012 Identity Server: \Program Files (x86)\novell\devman\jcc\certs\ 
<device> 


+ Windows Server 2012 Access Gateway Service: \Program 
Files\novell\devman\jcc\certs\<device> 


The <device> can be idp (for Identity Server) or esp (for the Embedded Service Providers including 
Access Gateways). 


To view the trust stores: 


1 Click Security > Trusted Roots. 
2 Select a trusted root, then click Add Trusted Roost to Trust Stores. 
3 Click the Select Keystore icon. 

The list can include the following trust stores: 


Trust Store: This Identity Server trust store contains the trusted root certificates of all the 
providers that it trusts. Liberty and SAML 2.0 protocol messages that are exchanged between 
identity and service providers often need to be digitally signed. A provider uses the signing 
certificate included with the metadata of a trusted provider to validate signed messages from the 
trusted provider. The trusted root of the CA that created the signing certificate for the provider 
needs to be in this trust store. 


To use SSL for exchanging messages between providers, each provider must trust the SSL 
certificate authority of the other provider. You must import the root certificate chain for the other 
provider. Failure to do so causes numerous system errors. 


This trust store is also used to store the trusted root certificates of the user stores that it has 
been configured to use. 


OCSP Trust Store: Identity Server uses this trust store for OCSP (Online Certificate Status 
Protocol) certificates. OCSP is a method used for checking the revocation status of a certificate. 
To use this feature, you must set up an OCSP server. Identity Server sends an OCSP request to 
the OCSP server to determine if a certain certificate has been revoked. The OCSP server replies 
with the revocation status. If this revocation checking protocol is used, Identity Server does not 
cache or store the information in the reply, but sends a request every time it needs to check the 
revocation status of a certificate. The OCSP reply is signed by the OCSP server. To verify that it 
was signed by the correct OCSP server, the OCSP server certificate needs to be added to this 
trust store. 
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12.3 


12.3.1 


ESP Trust Store (Access Gateway): Access Gateway ESP trust store contains the trusted root 
certificate of Identity Server that it has been configured to trust. It usually contains one certificate 
unless you configure Access Gateway to trust one Identity Server, and then modify Access 
Gateway to trust a different Identity Server. If you are using certificates generated by the Access 
Manager CA, the root certificate of this CA is automatically added to this trust store. If Identity 
Server is using a certificate generated by an external CA, you need to add the trusted root 
certificate of that CA to this trust store. 


Proxy Trust Store: When SSL is set up between Access Gateway and its Web servers, Access 
Gateway uses this trust store for the trusted root certificates of the Web servers. 


This trust store does not use the default location: 
+ Access Gateway Appliance: /opt/novell/apache2/cacerts 
+ Windows Access Gateway Service: \Program Files\Novell\apache\cacerts 


4 Click Cancel twice. 


Access Manager Keystores 


A keystore is a location, such as a file, containing keys and certificates. Access Manager components 
can access the keystore to retrieve certificates and keys as needed. Keystores for Access Manager 
are already defined for the components. 


Administration Console creates a keystore in the file system of the device that is assigned to the 
keystore. The operating system of the device determines the location: 
¢ Linux: /opt/novell/devman/jcc/certs/<device> 


+ Windows Server 2012 Identity Server: \Program Files (x86)\novell\devman\jcc\certs\ 
<device> 


+ Windows Server 2012 Access Gateway Service: \Program 
Files\novell\devman\jcc\certs\<device> 


The <device> can be idp (for Identity Server) and esp (for the Embedded Service Providers, including 
Access Gateways). 


To view the keystores: 
1 Click Security > Certificates. 
2 Click the name of a certificate, then click Add Certificate to Keystores. 
3 Click the Select Keystore icon. 
Access Manager creates keystores for the following devices: 
¢ “Identity Server Keystores” on page 944 


+ “Access Gateway Keystores” on page 945 
+ “Keystores When Multiple Devices Are Installed on Administration Console” on page 945 


Identity Server Keystores 


Access Manager creates the following keystores for each Identity Server cluster configuration: 


Signing: Contains the certificate that is used for signing the assertion or specific parts of the 
assertion. 


Encryption: Contains the certificate that is used to encrypt specific fields or data in assertions. 
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12.3.2 


12.3.3 


SSL Connector: Contains the certificate that Identity Server uses for SSL connections. If multiple 
devices are installed on the same machine, Identity Server uses the COMMON_TOMCAT_CLUSTER 
keystore. 


Provider Introductions SSL Connector: Contains the certificate that you configure when you set up 
Identity Server to provide introductions to service providers that are trusted members of a service 
domain. The subject name of this certificate needs to match the DNS name of the service domain. 


Consumer Introductions SSL Connector: Contains the certificate that you configure when you set 
up Identity Server to consume authentications provided by other identity providers that are trusted 
members of a service domain. The subject name of this certificate needs to match the DNS name of 
the service domain. 


Access Gateway Keystores 


Access Manager creates the following keystores for each Access Gateway or cluster: 


Signing: Contains the certificate that is used for signing logout requests from Access Gateway/ESP 
to Identity Server. 


Encryption: Contains the certificate that is used to encrypt specific fields or data in assertions. 


ESP Mutual SSL: Contains the certificate that is used for SSL when you have established SSL 
communication between Access Gateway and Identity Server. Identity Server and ESP 
communicates using mutual authentication. The public key (trusted root) of the certificate authority 
that created the certificate needs to be in Identity Server’s trust store. 


Proxy Key Store: Contains the certificate that is used for SSL when you have enabled SSL between 
a reverse proxy and the browsers. The public key (trusted root) of the certificate authority that created 
the certificate needs to be in browser’s trust store for the SSL connection to work without warnings. If 
you create multiple reverse proxies and enable them for SSL, each reverse proxy needs a certificate, 
and the subject name of the certificate needs to match the DNS name of the reverse proxy. 


This keystore does not use the default location: 


e Access Gateway Appliance: /opt/novell/apache2/certs 


+ Windows Access Gateway Service: \Program Files\Novell\apache\certs 


Keystores When Multiple Devices Are Installed on 
Administration Console 


Access Manager creates the following keystore when Identity Server is installed on Administration 
Console. 


COMMON_TOMCAT_CLUSTER: Contains the certificate that is used for SSL connections. 
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Creating Certificates 


Access Manager comes with certificates for testing purposes. The test certificates are called test- 
signing, test-encryption, test-provider, test-consumer, and test-connector. At a minimum, you must 
create two SSL certificates: one for Identity Server test-connector and one for Access Gateway 
reverse proxy. Then you replace the predefined certificates with the new ones. 


If you install a secondary Administration Console, the certificate authority (CA) is installed with the 
first instance of eDirectory, and the secondary consoles have eDirectory replicas and therefore no CA 
software. All certificate management must be done from the primary Administration Console. 
Certificate management commands issued from a secondary Administration Console can work only if 
the primary console is also running properly. Other commands can work independently of the primary 
console. 


NOTE: It is recommended to recreate the certificates after upgrading Access Manager to 4.2 or later. 
Certificates created in Access Manager 4.1 or earlier versions use SHA-1 ciphers by default. In 
Access Manager 4.2 onward, certificates are created using SHA-2 ciphers by default. 


IMPORTANT: Before generating any certificates with Administration Console CA, ensure that time is 
synchronized within one minute among all of your Access Manager devices. If the time of 
Administration Console is ahead of the device for which you are creating the certificate, the device 
rejects the certificate. 


1 Click Security > Certificates. 
2 Select from the following actions: 


New: To create a new certificate, click New. For information about the fields you need to fill in, 
see Section 13.1, “Creating a Locally Signed Certificate,” on page 948 and Section 13.4, 
“Generating a Certificate Signing Request,” on page 952. 


Delete: To delete a certificate, select the certificate, then click Delete. If the certificate is 
assigned to a keystore, a warning message appears. You must remove a certificate from all 
keystores before it can be deleted. 


Import Private/Public Keypair: To import a key pair, click Actions > Import Private/Public 
Keypair. For more information, see Section 14.6, “Importing a Private/Public Key Pair,” on 
page 960. 


Add Certificate to Keystores: To add a certificate to a keystore, click Actions > Add Certificate 
to Keystore. For more information, see Section 14.2, “Adding a Certificate to a Keystore,” on 
page 957. 


View Certificate Details: To view certificate details, renew a certificate, or export keys, click the 
name of the certificate. For more information, see Section 14.1, “Viewing Certificate Details,” on 
page 955. 
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13.1 


Creating a Locally Signed Certificate 


By default, the Access Manager installation process creates the local CA that can issue and sign 
certificates and installs a certificate server that generates certificates, keys, and CSRs (certificate 
signing requests) and imports certificates and keys. 

1 Click Security > Certificates > New. 


2 Select Use local certificate authority. 


This option creates a certificate signed by the local CA (or Organizational CA), and creates the 
private key. For information about creating a CSR, see “Generating a Certificate Signing 
Request” on page 952. 


Specify a unique, system-wide name for the certificate that you can easily associate with the 
certificate’s purpose. The name must contain only alphanumeric characters and no spaces.: 


For Subject, click Edit to display a dialog box that lets you add the appropriate attributes for the 
subject name. 


The subject is an X.500 formatted distinguished name that identifies the entity that is bound to 
the public key in an X.509 certificate. Choose the subject name that the browser expects to find 
in the certificate. The name you enter must be fully distinguished. Completing all the fields 
creates a fully distinguished name that includes the appropriate types (such as C for country, ST 
for state, L for location, O for organization, OU for organizational unit, and CN for common 
name). For example, cn=AcmeWebServer.ou=Sales.o=Acme.c=US. 


Common name: If you are creating a certificate for an Identity Server, specify the DNS name of 
Identity Server. If you are creating a certificate for an Access Gateway, specify the published 
DNS name of the proxy service. Specifying values for the other attributes is optional. 


For more information about the other attributes, see Section 13.2, “Editing the Subject Name,” 
on page 949. 


Click OK, then fill in the following fields: 
Signature algorithm: The algorithm you want to use (SHA-256 or SHA-512). 


Valid from: The date from which the certificate is valid. For externally signed certificates, the 
external certificate authority sets the validity period. 


Months valid: The number of months that the certificate is valid. 
Key size: The size of the key. Select 512, 1024, 2048, or 4096. 
(Optional) To configure advanced options, click Advanced Options. 
Configure the following options as necessary for your organization: 


Critical: Specifies that an application should reject the certificate if the application does not 
understand the key usage extensions. 


Encrypt other keys: Specifies that the certificate is used to encrypt keys. 


Encrypt data directly: Encrypts data for private transmission to the key pair owner. Only the 
intended receiver can read the data. 


Create digital signatures: Specifies that the certificate is used to create digital signatures. 


Non-repudiation: Links a digital signature to the signer and the data. This prevents others from 
duplicating the signature because no one else has the signer’s private key. Additionally, the 
signer cannot deny having signed the data. 


(Conditional) If you are creating a key for a certificate authority, configure the following options: 


This key is for a Certificate Authority: Specifies that this certificate is for the local 
configuration (eDirectory) certificate authority. 
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If you create a new CA, all the keys signed by the CA being replaced no longer have a trusted 
CA. You might also need to reassign the new CA to all the trust stores that contained the old CA. 


Critical: Enforces the basic constraints you specify. Select one of the following: 


+ Unlimited: Specifies no restriction on the number of subordinate certificates that the CA 
can verify. 


+ Do not allow intermediate signing certificates in certificate chain: Prevents the CA 
from creating other CAs, but it can create server or user certificates. 


+ Number of allowable intermediate signing certificates in signing chain: Specifies how 
many subordinate certificates are allowed in the certificate chain. Values must be 1 or more. 
Entering 0 creates only entity objects. 


9 (Optional) To create subject alternative names used by the certificate, click Edit Subject 
Alternate Names, then click New. 


Alternate names can represent the entity identified by the certificate. The certificate can identify 
the subject CN=www.OU=novell.O=com, but the subject can also be known by an IP address, 
such as 222.111.100.101, or a URI, such as www.novell.com, for example. For more information, 
see Section 13.3, “Assigning Alternate Subject Names,” on page 951. 


10 Click OK. 


11 (Conditional) If you assigned alternate names, determine how you want applications to handle 
the alternate names. Select Critical if you want an application that does not understand the 
alternate name extensions to reject the certificate. 


12 Click OK. 


13.2 Editing the Subject Name 


1 Fill in one or more of the following attributes. 
The following attributes are the most common ones used in certificate subjects: 
Common name: The DNS name of the server. 


Specify the value, for example AcmeWebServer.provo.com. Do not include the type (cn=). The 
UI adds that for you. 


For Identity Server, this is the domain name of the base URL of Identity Server configuration. 
This value cannot be an IP address or begin with a number, to ensure that trust does not fail 
between providers. 


For Access Gateway, this is the published DNS name of the proxy service. 
Organizational unit: Describes departments or divisions. 
Organization: Differentiates between organizational divisions. 
City or town: Commonly referred to as the Locality. 
State or province: Commonly referred to as the State. Do not abbreviate the name. 
Country: The country, such as US. 

2 Use the drop-down menus to add additional attributes. 


These values allow you to specify additional fields that are supported by eDirectory, and you can 
include them as part of the subject to further identify the entity represented by the certificate. 


CN: The Common name attribute in the list of Commonly used attributes (OID: 2.5.4.3) 
C: The Country attribute in the list of Commonly used attributes (OID: 2.5.4.6) 
SN: The surname attribute (OID: 2.5.4.4) 
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L: The locality attribute, which is the City or town attribute in the list of Commonly used 
attributes (OID: 2.5.4.7) 


ST: The State or province attribute in the list of Commonly used attributes (OID: 2.5.4.8) 

S: The State or province attribute in the list of Commonly used attributes (OID: 2.5.4.8) 

O: The Organization attribute in the list of Commonly used attributes (OID: 2.5.4.10) 

OU: The Organizational unit attribute in the list of Commonly used attributes (OID: 2.5.4.11) 
street: Describes the street address (OID: 2.5.4.9) 

serialNumber: Specifies the serial number of a device (OID: 2.5.4.5) 

title: Describes the position or function of an object (OID: 2.5.4.12) 

description: Describes the associated object (OID: 2.5.4.13) 

searchGuide: Specifies a search filter (OID: 2.5.4.14) 


businessCategory: Describes the kind of business performed by an organization (OID: 
2.5.4.15) 


postalAddress: Specifies address information required for the physical delivery of postal 
messages (OID: 2.5.4.16) 


postalCode: Specifies the postal code of an object (OID: 2.5.4.17) 
postOfficeBox: Specifies the post office box for the physical delivery of mail (OID: 2.5.4.18) 


physicalDeliveryOfficeName: Specifies the name of the city or place where a physical delivery 
office is located (OID: 2.5.4.19) 


telephoneNumber: Specifies a telephone number (OID: 2.5.4.20) 
telexNumber: Specifies a telex number (OID: 2.5.4.21) 
teletexTerminalldentifier: Specifies an identifier for a telex terminal (OID: 2.5.4.22) 


facsimileTelephoneNumber: Specifies the telephone number for a facsimile terminal (OID: 
2.5.4.23) 


x121Address: Specifies the address used in electronic data exchange (OID: 2.5.4.24) 


internationallSDNNumber: Specifies an international ISDN number used in voice, video, and 
data transmission (OID: 2.5.4.25) 


registeredAddress: Specifies the postal address for the delivery of telegrams or expedited 
documents (OID: 2.5.4.26) 


destinationIndicator: Specifies an attribute used in telegram services (OID: 2.5.4.27) 


preferredDeliveryMethod: Specifies the preferred delivery method for a message (OID: 
2.5.4.28) 


presentationAddress: Specifies an OSI presentation layer address (OID: 2.5.4.29) 


supportedApplicationContext: Specifies the identifiers for the OSI application contexts in the 
application layer (OID: 2.5.4.30) 


member: Specifies the distinguished name of an object associated with a group or a list (OID: 
2.5.4.31) 


owner: Specifies the name of an object that has responsibility for another object (OID: 2.5.4.32) 


roleOccupant: Specifies the distinguished name of an object that fulfills an organizational role 
(OID: 2.5.4.33) 


seeAlso: Specifies the distinguished name of an object that contains additional information 
about the same real-world object (OID: 2.5.4.34) 


userPassword: Specifies the object's password (OID: 2.5.4.35) 
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name: Specifies a name that is in the UTF-8 form of the ISO 10646 character set (OID: 2.5.4.41) 
givenName: Specifies the given or first name of an object (OID: 2.5.4.42) 
initials: Specifies the initials of an object (OID: 2.5.4.43) 


generationQualifier: Specifies the generation of an object, which is usually a suffix (OID: 
2.5.4.44) 


x500Uniqueldentifier: Specifies an identifier that distinguishes between objects when a DN has 
been reused (OID: 2.5.4.45) 


dnQualifier: Specifies information that makes an object unique when information is being 
merged from multiple sources and objects could have the same RDNs (OID: 2.5.4.46) 


enhancedSearchGuide: Specifies a search filter used by X.500 users (OID: 2.5.4.47) 


protocolinformation: Specifies information that is used with the presentationAddress attribute 
(OID: 2.5.4.48) 


distinguishedName: Specifies the distinguished name of an object (OID: 2.5.4.49) 


uniqueMember: Specifies the distinguished name of an object associated with a group or a list 
(OID: 2.5.4.50) 


houseldentifier: Identifies a building within a location (OID: 2.5.4.51) 
dmdName: Specifies a directory management domain (OID: 2.5.4.54) 

E: Specifies an e-mail address. 

EM: Specifies an e-mail address. 

DC: Specifies the domain name for an object (OID: 0.9.2342.19200300.100.1.25) 


uniquelD: Contains an RDN-type name that can be used to create a unique name in the tree 
(OID: 0.9.2342.19200300.100.1.1) 


T: Specifies the name of the tree root object (OID: 2.16.840.1.113719.1.1.4.1.181) 
OID: Specifies an object identifier in dot notation. 


3 To create a certificate, continue with Step 5 on page 948, or to create a signing request, continue 
with Step 5 on page 952. 


13.3 Assigning Alternate Subject Names 


1 Fill in the following fields: 


Name Type: Names as specified by RFC 2459. Use the drop-down list to specify a name type, 
such as: 


+ Directory name: An X.500 directory name. The required format for the name is 
.<attribute name>=<attribute value>. For example: 
.0=novell.C=US 


Access Manager supports the following attributes: 


Country (C) 

Organization (O) 
Organizational Unit (OU) 
State or Province (S or ST) 
Locality (L) 

Common Name (CN) 


+ IP Address: An IP address such as 222.123.123.123 
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+ URI: A URI such as www.novell.com. 

¢ Registered ID: An ASN.1 object identifier. 

+ DNS Name: A domain name such as novell.com. 

+ Email Address (RFC 822 name): An e-mail address such as ca@novell.com. 


+ X400 Name: The messaging and e-mail standard specified by the ITU-TS (International 
Telecommunications Union - Telecommunication Standard Sector). It is an alternative to the 
more prevalent Simple Mail Transfer Protocol (SMTP) e-mail protocol. X.400 is common in 
Europe and Canada. 


+ EDI Party: EDI (Electronic Data Interchange) is a standard format for exchanging business 
data. 


+ Other: A user-defined name. 
Name: The display alternative name. 


2 Continue with Step 10 on page 949. 


13.4 Generating a Certificate Signing Request 


952 


Click Security > Certificates > New. 
To create a certificate signing request (CSR), select Use external certificate authority. 


This option generates a CSR for you to send to the CA for signing. A third-party CA is managed 
by a third party outside of the eDirectory tree. An example of a third party CA is VeriSign. After 
the signed certificate is received, you need to import the certificate. 


Specify a Certificate name. 


Pick a unique, system-wide name for the certificate that you can easily associate with the 
certificate’s purpose. The name must contain only alphanumeric characters and no spaces. 


Click the Edit button to display a dialog box that lets you add appropriate locality information 
types for the subject name. 


For more information, see Section 13.2, “Editing the Subject Name,” on page 949. 
Click OK, then fill in the following fields: 
Signature algorithm: The algorithm you want to use (SHA-256 or SHA-512). 


Valid from: The date from which the certificate is valid. For externally signed certificates, the 
external certificate authority sets the validity period. 


Months valid: The number of months that the certificate is valid. 
Key size: The size of the key. Select 512, 1024, 2048, or 4096. 


(Conditional) If you are creating a key for a certificate authority, click Advanced Options, then 
configure the following: 


This key is for a Certificate Authority: Select this option. 
Critical: Enforces the basic constraints you specify. Select one of the following: 


+ Unlimited: Specifies no restriction on the number of subordinate certificates that the CA 
can verify. 


+ Do not allow intermediate signing certificates in certificate chain: Prevents the CA 
from creating other CAs, but it can create server or user certificates. 


+ Number of allowable intermediate signing certificates in signing chain: Specifies how 
many subordinate certificates are allowed in the certificate chain. Values must be 1 or more. 
Entering 0 creates only entity objects. 
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7 Click OK. 

8 Click the name of the certificate, copy the CSR data and send the information to the external CA. 
The certificate status is CSR Pending until you import the signed certificate. 

9 Click Close. 


10 When you receive the signed certificate and the trusted root (CA chain), continue with “Importing 
a Signed Certificate” on page 953. 


Importing a Signed Certificate 


After you receive the signed certificate and the CA chain, you must import it. CA can return the 
certificate in multiple ways. Typically, the CA either returns one or more files each containing one 
certificate, or returns a file with multiple certificates in it. 


The following figure illustrates a certificate chain example. 


Figure 13-1 Illustration of a Certificate Chain Example 


Signed by Signed by Signed by 
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Intermediate { Intermediate Root cert 
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To import this certificate chain: 


Certificate Chain Example: 


1 In Administration Console Dashboard, click Security > Certificates, then click the name of a 
certificate that is in a CSR Pending state. 


2 Click Import Signed Certificate. 


3 In the Import Signed Certificate dialog box, browse to locate the Entity certificate data file or 
paste the Entity certificate data text into the Certificate data text field. 


4 To import the CA chain, click Add trusted root and then locate the Root certificate data. 


5 Click Add intermediate certificate if you need to continue adding certificates to the chain for 
example, add Intermediate cert 1 and cert 2 in that order. 


6 Click OK, then click Close on the Certificate Details page. 


The certificate is now available for use by Access Manager devices. 


NOTE: When there is a server certificate and more than two intermediate CA certificates, use PKCS7 
format file and import the certificate and its CA chain. 


If you receive an error when attempting to import the certificate, see Chapter 30.5, “Troubleshooting 
Certificate Issues,” on page 1221. 
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Managing Certificates and Keystores 


You can import certificates created by an external certificate authority. These certificates then need to 
be assigned to a device by adding the certificate to the device’s keystore. The subject name of the 
certificate needs to match the DNS name of the device, or if you are using wildcard certificates, the 
main domain name needs to match. You can perform the following certificate tasks: 


+ 


+ 


+ 


+ 


+ 


Section 14.1, “Viewing Certificate Details,” on page 955 


Section 14.2, “Adding a Certificate to a Keystore,” on page 957 


Section 14.3, “Renewing a Certificate,” on page 958 


Section 14.4, “Exporting a Private/Public Key Pair,” on page 959 


Section 14.5, “Exporting a Public Certificate,” on page 959 


Section 14.6, “Importing a Private/Public Key Pair,” on page 960 


Section 14.7, “Managing Certificates in a Keystore,” on page 960 


Section 14.8, “Using Multiple External Signing Certificates,” on page 962 


14.1 Viewing Certificate Details 


The Certificate Details page lists the properties of a certificate, such as certificate type, name, 
subject, and assigned keystores. The fields are not editable. 


1 Click Security > Certificates. 
2 Select one of the following: 


+ Click the name of a certificate that is not ina CSR Pending state. The Certificate Details 
page contains the following information about the certificate: 


Field 

Issuer 

Serial number 
Subject 

Valid from 
Valid to 


Devices 


Key size 


Signature algorithm 


Description 

The name of the CA that created the certificate. 
The serial number of the certificate. 

The subject name of the certificate. 

The first date and time that the certificate is valid. 
The date and time that the certificate expires. 


The devices that are configured to hold this certificate on their file 
system and the keystore that holds them. 


The key size that was used to create the certificate. 


The signature algorithm that was used to create the certificate. 
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Field 


Finger print (MD5) 


Finger print (SHA256) 


Subject Alternate Names: 


Critical 


Key Usage: Critical 


Sign CRLs 


Sign certificates 
Encrypt other keys 


Encrypt data directly 


Create digital signatures 


Non-repudiation 


CRL Distribution Points 


Authority Info Access 
(OCSP) 
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Description 


The certificate's message digest that was calculated with the MD5 
algorithm. It is embedded into the certificate at creation time. It can 
be used to uniquely identify a certificate. For example, users can 
verify that a certificate is the one they think it is by matching this 
published MD5 fingerprint with the MD5 fingerprint on the local 
certificate. 


The certificate's message digest that was calculated with the SHA- 
256 algorithm. It is embedded into the certificate at creation time. It 
can be used to uniquely identify a certificate. For example, users can 
verify that a certificate is the one they think it is by matching a 
published SHA-256 fingerprint with the SHA-256 fingerprint on the 
local certificate. 


Indicates whether an application should reject the certificate if the 
application does not understand the alternate name extensions. Any 
configured alternate names are displayed in the list. 


Indicates whether an application should reject the certificate if the 
application does not understand the key usage extensions. 


Indicates whether the certificate is used to sign CRLs (Certificate 
Revocation Lists). 


Indicates whether the certificate is used to sign other certificates. 
Indicates whether the certificate is used to encrypt keys. 


Indicates whether the certificate can encrypted data for private 
transmission to the key pair owner. Only the intended receiver can 
read the data. 


Indicates whether the certificate can create digital signatures. 


Indicates whether the certificate links a digital signature to the signer 
and the data. This prevents others from duplicating the signature 
because no one else has the signer’s private key. Additionally, the 
signer cannot deny having signed the data. 


A list of Certificate Revocation List (CRL) distribution points that are 
embedded into the certificate as an extension at certificate creation 
time. Implementations search the CRL from each distribution point 
(the distribution point is usually a URI that points to a store of 
revoked certificates) to see whether a certificate has been revoked. 


A list of Online Certificate Status Protocol (OCSP) responders that 
are embedded into the certificate as an extension at certificate 
creation time. Implementations query the OCSP responder to see 
whether a certificate has been revoked. 


+ Click the name of a certification in a CSR Pending state. The following information is 


displayed: 

Subject The subject name of the certificate. 

Valid from The date and time that the request was generated. 

Valid to The date and time that the request expires. 

Devices No entries. ACSR cannot be assigned to a device. 

Key size The key size that was used to create the request. 

Signature algorithm The signature algorithm that was used to create the request. 

State Displays CSR Pending, indicating that the request has been 
generated. 

CSR data The certificate signing request data. You can either export this data 


or copy and paste it into CA’s request tool. 


3 (Conditional) For a certificate not ina CSR Pending state, select one of the following actions: 


Renew: Allows you to renew the certificate. For more information, see Section 14.3, “Renewing 
a Certificate,” on page 958. 


Export Private/Public Keypair: Allows you to export private certificates to obtain a backup 
copy of the key, to move the key to a different server, or to share the key between servers. For 
more information, see Section 14.4, “Exporting a Private/Public Key Pair,” on page 959 


Export Public Certificate: Allows you to export a public key certificate to a file. For more 
information, see Section 14.5, “Exporting a Public Certificate,” on page 959. 


Add Certificate to Keystores: Allows you to assign the certificate to keystore so it can be used 
by Access Manager. For more information, see Section 14.2, “Adding a Certificate to a 
Keystore,” on page 957. 


4 (Conditional) For a certificate in a CSR Pending state, select one of the following actions: 


Import Signed Certificate: Allows you to import the certificate that was generated for this 
request. For more information, see Section 13.5, “Importing a Signed Certificate,” on page 953. 


Export CSR: Allows you to export the CSR to a CSR file. 


NOTE: Whenever the configuration store contains a Key Material Object (KMO) with a CSR in 
pending state, the KMO will not be exported by using the amdiagcfg script and not be backed up 
by using the ambkup script. 


14.2 Adding a Certificate to a Keystore 


After importing a certificate, you need to assign the certificate to keystore before it is used by Access 
Manager. 
1 Click Security > Certificates. 
2 Select a certificate. 
3 Click Actions > Add Certificate to Keystores. 
4 Specify the keystore to which you are adding the certificate. To locate a keystore: 
4a Click Select Keystore. 
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For a description of the Access Manager keystores, see Section 12.3, “Access Manager 
Keystores,” on page 944. 


4b On the Keystore Details page, select the keystore, then click OK. 
5 Fill in the following fields: 
Alias: Specify the certificate alias. 


Overwrite keys with same alias: Select whether to overwrite certificates with the same alias, if 
the alias you specify is already in use in that keystore. 


6 Click OK. 
7 Update the devices that are using this keystore. 


14.3 Renewing a Certificate 
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The Certificate Details page lists the properties of a certificate, such as certificate type, name, 
subject, and assigned keystores. This page also includes the original CSR when the certificate is still 
in a pending state (for example, you have generated the CSR, but you have not yet received and 
imported the signed certificate). If the certificate is expiring, you can cut and paste its text to send it to 
the CA to get a renewed certificate, then import the newly signed certificate. 


For the certificates that Access Manager uses internally, a certificate process is started with Tomcat. 
This process runs once every 24 hours. It checks all the internal certificates and determines if they 
are going to expire within 30 days. If they are due to expire, the process automatically regenerates 
the certificate or trusted root. When a certificate is regenerated, the following message appears: 


One or more automatically created certificates were regenerated. Reboot the entire 
administration console as soon as possible to avoid interruption of service. 


This message appears when the administrator logs in to Administration Console, or if the 
administrator is already logged in, when the administrator switches from one page to another. 


This event is also auditing. Another audit event is also generated which tells the administrator to 

restart any effected services. When Administration Console certificate and the eDirectory certificates 
are expiring, a log entry is written to the app_sc log file. The log entry contains the “Recreating auto- 
generated certificates” string as well as a couple success or failure messages per key re-generated. 


Certificates and trusted roots that are manually created with the Access Manager CA or are imported 
into Administration Console use a different process. The administrator is warned that these 
certificates are expiring when the administrator logs in to Administration Console. The following 
message is displayed: 


Warning: the following certificates are expired or will expire within X days: 
<certA>, <certB>. 


This message is displayed each time the administrator logs in to Administration Console. Events for 
the expiration of these certificates are not audited and are not logged. 


The following figure illustrates the certificate chain example. 


Figure 14-1 Illustration of a Certificate Chain Example 
signed by Signed by Signed by 


J ' 
Entity cert ~~ Intermediate | Root cert 
cert 1 (Trusted root) 


Certificate Chain Example: 
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14.4 


14.5 


To renew a certificate: 


Click Security > Certificates. 
Click the certificate name. 
Click Renew. 
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On the Renew page, either browse to locate and select the certificate or select the Certificate 
data text (PCM/Base64) option and paste the certificate data into the text box. 


5 To import the CA chain, click Add trusted root and then locate the Root certificate data. 
6 Update the device using the certificate. 


7 Click Add intermediate certificate if you need to continue adding certificates to the chain for 
example, add Intermediate cert 1 and cert 2 in that order. 


8 Click OK, then click Close. 


Exporting a Private/Public Key Pair 


When you create a certificate, you can specify whether it is exportable. If a key is exportable, it can be 
extracted and put in a file along with the associated certificate. The file is written in an industry 
standard format, PKCS#12, which allows it to be transported to other platforms. It is encrypted with a 
user-specified password to protect the private key. You can export private certificates to obtain a 
backup copy of the key, to move the key to a different server, or to share the key between servers. 


You cannot export a certificate if you enabled the Do not allow private key to be exportable option 
while creating the certificate. 

Click Security > Certificates. 

On the Certificates page, click the certificate. 

On the Certificate Details page, click Export Private/Public Keypair. 


BW N FP 


Select a format for the key: 


PFX/PKCS12: Public Key Cryptography Standards #12 (PKCS#12) format, which is also called 
PFX format. This format can be used to create JKS or PEM files. 


JKS: Java keystore format. 
5 Specify the password in the Encryption/decryption password field, then click OK. 


IMPORTANT: Remember this password because you need it to re-import the key. 


6 Click OK. 


Exporting a Public Certificate 

You can export a trusted root or a public key certificate to a file so that a client can use it to verify the 
certificate chain sent by a cryptography-enabled application, or to have a backup copy of the file. 
You can export the certificate in the following formats: 


+ DER-encoded (.der) to a file. 


+ PEM-encoded to a file. This is a Base64-encoded DER certificate that is enclosed between the 
BEGIN CERTIFICATE and END CERTIFICATE tags. 


+ PEM CUT/Paste Buffer. This displays the certificate data so you can copy it to the system 
Clipboard. You can then pasted it directly into a cryptography-enabled application. 
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14.6 


14.7 


To export the public certificate: 


1 
2 
3 
4 


In Administration Console Dashboard, click Security > Certificates. 

Click the certificate name. 

On the Certificate Details page, click Export Public Certificate, then click the file type. 
Save the output file to the location of your choosing. 


Importing a Private/Public Key Pair 


If you created a key pair that was exported from another certificate management system, you can 
import the key pair and then assign it to an Access Manager device. The file needs to be in PFX/ 
PKCS12 (*.pfx or *.p12) format. 


1 
2 
3 


5 


Click Security > Certificates. 
Select Actions > Import Private/Public Keypair. 
Fill in the following fields: 


Certificate name: The name of the certificate. This is a system-wide, unique name used by 
Access Manager. The name must contain only alphanumeric characters and no spaces. If the 
name starts with a number, an underline (_) prefix is added to the name so that the name 
conforms to XML requirements. If the name contains invalid characters, it is automatically 
renamed. 


Keystore password: Type the encryption/decryption password established when exporting the 
certificate. 


Certificate data file (PFX/PKCS12): The certificate file to import. You can browse to locate the 
* pfx or *.p12 file. 

Certificate data file (JKS): To locate a JKS file, select this option, then click Browse. 

Click OK. 


If you receive an error when importing the certificate, the error comes from either NICI or PKI. 
For a description of these error codes, see Novell Certificate Server Error Codes and Novell 
International Cryptographic Infrastructure (http://www.novell.com/documentation/nwec/ 
index.html). For general certificate import issues, see “Importing an External Certificate Key Pair 
on page 1222. 


Continue with “Adding a Certificate to a Keystore” on page 957. 


Managing Certificates in a Keystore 


The 


Keystore Details page allows you to view associated cluster member keystores and to replace 


certificates associated with the keystore. 


Not all keystores are associated with a cluster configuration. Those that are (for example, the Signing 
and Encryption keystores) display the following information: 


Column Description 
Keystore Name The name of the keystore. 
Type The type of keystore, such as Java or PKCS12. 


Device or Cluster Name The name of the device or of the cluster that is using the keystore. 
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Some keystores require a single certificate, so you can only replace the certificate. Other keystores 
can contain multiple certificates. In this type of keystore, you can add and remove certificates. 


To view a keystore: 


1 Click Security > Certificates. 
2 Click the down-arrow in the Devices column, then select a keystore. 


3 Alternatively, Identity Server keystores can be accessed from Identity Server Cluster > Edit > 
General > Security. 


4 View the details of the keystore, the device associated with the keystore, and the certificates in 
the keystore. 


5 Add, Remove, and Replace options are available based on the type of keystore. They can be 
used for managing the certificates in the keystore. 


6 Toremove a certificate: 
6a Select the certificate, then click Remove. 


NOTE 
+ You cannot remove the default certificates or the certificates that are in use. 
¢ This option is available only for keystores that support multiple certificates. 


7 To add or replace a certificate: 
7a Click Add or Replace. 
7b Fill in the following fields: 


Certificate: Specifies the certificate you want to add. You can browse to locate the 
certificate. When you browse, the system displays the Select Certificate page. Select the 
certificate, then click OK. 


Alias(es): Specifies the certificate alias. This name is displayed among the list of 
certificates assigned to the keystore. By default, the certificate name is the alias name. You 
can change the name of the alias. 


Overwrite keys with the same alias: Enable this option if you want to overwrite the 
existing certificate with the given alias name. 


NOTE 
+ The Add and Remove option is available only for Encryption and Signing certificates. 
+ The Replace option allows you to only replace the default certificates. 


7c Click OK. 
8 Click Close. 
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14.8 Using Multiple External Signing Certificates 


Access Manager can use multiple external certificates for signing SAML 2.0 service providers. The 
external certificates can be from a single or multiple external keystores or HSMs. However, the 
certificates must be exportable as Access Manager does not send payloads to be signed to an 
external device. 


Perform the following steps to use multiple external signing certificates: 


1 Configure certificates for Access Manager Identity Server. 
1a Configure the externKeystore. properties file for multiple signing certificate: 
The format is: 


#KeyStore 1. 
com.novell.nidp.extern.signing.providerClass.1=<SOME CLASS> 
com.novell.nidp.extern.signing.providerName.1=<SOME PROVIDER NAME> 
com.novell.nidp.extern.signing.keystoreType.1=<SOME KEYSTORE TYPE> 
com.novell.nidp.extern.signing.keystoreName.1=<SOME KEYSTORE NAME> 
com.novell.nidp.extern.signing.keystorePwd.1=<SOME PASSWORD> 
#Aliases and key passwords. 
com.novell.nidp.extern.signing.alias.1.1=<SOME ALIAS> 
com.novell.nidp.extern.signing.keyPwd.1.1=<SOME PASSWORD> 
com.novell.nidp.extern.signing.alias.1.2=<SOME ALIAS> 
com.novell.nidp.extern.signing.keyPwd.1.2=<SOME PASSWORD> 


com.novell.nidp.extern.signing.alias.1.n=<SOME ALIAS> 
com.novell.nidp.extern.signing.keyPwd.1.n=<SOME PASSWORD> 


#KeyStore 2. 
com.novell.nidp.extern.signing.providerClass.2=<SOME CLASS> 
com.novell.nidp.extern.signing.providerName.2=<SOME PROVIDER NAME> 
com.novell.nidp.extern.signing.keystoreType.2=<SOME KEYSTORE TYPE> 
com.novell.nidp.extern.signing.keystoreName.2=<SOME KEYSTORE NAME> 
com.novell.nidp.extern.signing.keystorePwd.2=<SOME PASSWORD> 
#Aliases and key passwords. 
com.novell.nidp.extern.signing.alias.2.1=<SOME ALIAS> 
com.novell.nidp.extern.signing.keyPwd.2.1=<SOME PASSWORD> 


com.novell.nidp.extern.signing.alias.2.n=<SOME ALIAS> 
com.novell.nidp.extern.signing.keyPwd.2.n=<SOME PASSWORD> 


For Keystore parameters, the suffix is a single integer after the last period, for example, “.1” 
and “.2”. 


For aliases and key passwords, the suffix contains two integers. First integer for the 
keystore and second for the key, separated by dots, such as “.1.1” or “.1.2” for keys of 
keystore 1 and “.2.1” for the key of keystore 2. 


The default signing key is configured as one of the following: 


com.novell.nidp.extern.signing.providerClass=<SOME CLASS> 
com.novell.nidp.extern.signing.providerName=<SOME PROVIDER NAME> 
com.novell.nidp.extern.signing.keystoreType=<SOME KEYSTORE TYPE> 
com.novell.nidp.extern.signing.keystoreName=<SOME KEYSTORE NAME> 
com.novell.nidp.extern.signing.keystorePwd=<SOME PASSWORD> 
com.novell.nidp.extern.signing.alias=<SOME ALIAS> 
com.novell.nidp.extern.signing.keyPwd=<SOME PASSWORD> 
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com.novell.nidp.extern.signing.providerClass.1=<SOME CLASS> 
com.novell.nidp.extern.signing.providerName.1=<SOME PROVIDER NAME> 
com.novell.nidp.extern.signing.keystoreType.1=<SOME KEYSTORE TYPE> 
com.novell.nidp.extern.signing.keystoreName.1=<SOME KEYSTORE NAME> 
com.novell.nidp.extern.signing.keystorePwd.1=<SOME PASSWORD> 
com.novell.nidp.extern.signing.alias.1.1=<SOME ALIAS> 
com.novell.nidp.extern.signing.keyPwd.1.1=<SOME PASSWORD> 


1b Open the /opt/novell/nam/idp/conf/tomcat .conf file. 
1c Add the following: 


JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.nidp.extern.config.file=[path-to- 
file]/externKeystore.properties" 


1d Restart services. 


2 Assign the certificate to the service provider. The external keystore certificates are not listed in 
Administration Console. 


2a To assign a certificate from the external keystore, select any one of the listed certificate and 
provide alias as name of the certificate to be assigned. 


2b Reimport metadata and certificates. 
2c Restart services. The certificate from external keystore is used to federate. 


NOTE: This is a general configuration and may vary based on HSM providers. 


Example of Creating an External Keystore and Certificates 


This example provides steps to configure Java KeyStore (JKS) as an external keystore, add 
certificates in JKS, and assign it to a service provide for federation. 
1 Run the following command to configure JKS as an external keystore and add a certificate: 


keytool -keystore /tmp/namKeyStore/namKeyStore.jks -storepass password - 
genkeypair -alias namExtCert1 -keyalg RSA -keysize 2048 -validity 60 -keypass 
password 


Provide: [Optional] 
First and Last Name 
Organizational Unit 
Organization 
City 
State 
Country-Code 


Here, keytool is the command used to create a keystore namKeyStore. jks at /tmp/ 
namKeyStore/. A keypair with the alias namExtCert1 has been created and added to the 
keystore. 


2 Run the following command to add another certificate to the keystore: 


keytool -genkey -alias namExtCert2 -keyalg RSA -keypass password2 -storepass 
password -keystore /tmp/namKeyStore/namKeyStore. jks 


Here, the keytool command is used to create a keypair with the alias namExtCert2 and add it to 
the namKeyStore. jks keystore. 


Managing Certificates and Keystores 963 


3 Create a properties file, namKeyStore.properties at /tmp/namKeyStore/ and add the 
following content: 


# KeyStore Type. 
com.novell.nidp.extern.signing.providerClass.1=sun.security.rsa.SunRsaSign 


com.novell.nidp.extern.signing.providerName.1=SunRsaSign 
com.novell.nidp.extern.signing.keystoreType.1=JKS 


# KeyStore name and password. com.novell.nidp.extern.signing.keystoreName.1=/ 
tmp/namKeyStore/namKeyStore. jks 
com.novell.nidp.extern.signing.keystorePwd.1=password 


#Aliases and key passwords. 
com.novell.nidp.extern.signing.alias.1.1=namExtCert1 
com.novell.nidp.extern.signing.keyPwd.1.1=password 


com.novell.nidp.extern.signing.alias.1.2=namExtCert2 


com.novell.nidp.extern.signing.keyPwd.1.2=password2 
4 Open the /opt/novell/nam/idp/conf/tomcat .conf file and add the following content: 


JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.nidp.extern.config.file=/tmp/namKeyStore/ 
namKeyStore. properties" 


5 Restart services. 


6 Go to Administration Console and assign the certificate to the service provider. See Step 2 on 
page 963. 
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Assigning Certificates to Access 
Manager Devices 


After you assign certificates to devices, the certificates are placed in keystores. Ensure that you 
update the device so that the certificates are pushed into active use. 


This section discusses how you update, renew, and assign certificates to Access Manager Devices. 


¢ Section 15.1, “Importing a Trusted Root to the LDAP User Store,” on page 965 
¢ Section 15.2, “Managing Identity Server Certificates,” on page 965 
¢ Section 15.3, “Assigning Certificates to an Access Gateway,” on page 967 


e Section 15.4, “Changing a Non-Secure (HTTP) Environment to a Secure (HTTPS) 
Environment,” on page 969 


15.1 Importing a Trusted Root to the LDAP User Store 


When you specify the settings of a user store for an Identity Server configuration, or add a user store, 
you can import the trusted root certificate to the LDAP user store device. 


1 In Administration Console Dashboard, click Devices > Identity Servers > Edit > Local > [User 
Store]. 
2 Under Server Replicas, click the name of the server replica. 
3 Enable the Use secure LDAP connections option. 
This option allows SSL communication to occur between Identity Server and the user store. 
4 Click Auto import trusted root. 
5 Click OK to confirm the import. 
Ensure that you have pop-ups enabled, or the browser cannot display the Confirm dialog box. 
6 Select one of the certificates in the list. 


You are prompted to choose either a server certificate or a root CA certificate. To trust one 
certificate, choose Server Certificate. Choose Root CA Certificate to trust any certificate signed 
by that certificate authority. 


7 Specify an alias, then click OK. 

You use the alias to identify the certificate in Access Manager. 
8 On the User Store page, click OK. 
9 Restart Identity Server. 


15.2 Managing Identity Server Certificates 


Identity Server stores certificates in keystores and trust stores. Keystores can hold only one 
certificate. Trust stores can hold multiple trusted roots. After you install Identity Server, you should 
replace the default certificates in the keystore. You should create an SSL certificate for Identity Server 
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and use it to replace the predefined test-connector certificate that comes with Access Manager. You 
can also replace the test-provider and test-consumer certificates in the Provider Introductions SSL 
Connector and Consumer Introductions SSL Connector keystores. The steps for replacing the 
signing, encryption, provider, and consumer certificates are similar. 


You can also add trusted roots to the trust store used by Identity Server, delete imported trusted roots, 
or auto-import them from a server. Trust store is the certificate container for CA certificates that 
Identity Server has been configured to trust. It needs to contain the trusted root for the identity 
providers, service providers, and embedded service providers that it has been configured to trust. 


You can also access the OCSP trust store to add OCSP server certificates. Online Certificate Status 
Protocol is a method used for checking the revocation status of a certificate. For this feature, you 
must set up an OCSP server. Identity Server sends an OCSP request to the OCSP server to 
determine if a certain certificate has been revoked. The OCSP server replies with the revocation 
status. If this revocation checking protocol is used, Identity Server does not cache or store the 
information in the reply, but sends a request every time it needs to check the revocation status of a 
certificate. The OCSP reply is signed by the OCSP server. To verify that it was signed by the correct 
OCSP server, the OCSP server certificate needs to be added to this trust store. The OCSP server 
certificate itself is added to the trust store, not the CA certificate 

1 In Administration Console Dashboard, click Devices > Identity Servers > Edit > Security. 

2 To replace a certificate in a keystore: 

2a Click the keystore link that contains the certificate you want to replace: 


Encryption: Displays the encryption certificate keystore. The encryption certificate is used 
to encrypt specific fields or data in the assertions. 


Signing: Displays the signing certificate keystore. Click this option to access the keystore 
and replace the signing certificate as necessary. The signing certificate is used to sign the 
assertion or specific parts of the assertion. 


SSL: Displays the SSL connector keystore. Click this option to access the keystore and 
replace the SSL certificate as necessary. This certificate is used for SSL connections. 


Provider: Displays the identity provider keystore. Click this option to access the keystore 
and replace the identity provider certificate. 


Consumer: Displays the identity consumer keystore. Click this option to access the 
keystore and replace the identity consumer certificate as necessary. 


2b Click Replace. 


A keystore stores only one certificate at a time. When you replace a certificate, you 
overwrite the existing one. 


2c In the Replace dialog box, click the Select Certificate icon and browse to select the 
certificate you created in Section 13, “Creating Certificates,” on page 947. 


2d Click OK. 
2e Click OK in the Replace dialog box. 
2f Restart Tomcat. 


The system restarts Tomcat for you if you click Restart Now at the prompt. If you want to 
restart at your convenience, select Restart Later and then manually restart Tomcat. 


Linux: Enter the following command: 

/etc/init.d/novell-idp restart OR rcnovell-idp restart 
Windows: Enter the following commands: 

net stop Tomcat7 


net start Tomcat7 
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3 To modify the trusted roots in the Trust Store: 
3a Click the name of the trust store that you want to manage. 


NIDP Trust Store: Contains the trusted root certificates of all the providers that Identity 
Server trusts. 


OCSP Trust Store: Contains the certificates of the OCSP servers that Identity Server 
trusts. 


3b To add a trusted root that you have saved in a file, click Add. 
3c To remove a trusted root, select the trusted root, then click Delete. 


3d To download the trusted root from the server, click Auto-Import From Server, specify the 
DNS or IP address of the server, enter the port, then click OK. 


3e Select the certificate to add, specify an alias, then click OK. 
3f Update Identity Server configuration on the Servers page, as prompted. 


15.3 Assigning Certificates to an Access Gateway 


Access Gateway can be configured to use certificates for SSL communication with three types of 
entities: 


¢ Identity Server: Access Gateway uses the Embedded Service Provider to communicate with 
Identity Server. The Access Manager CA automatically generates the required certificates for 
secure communication when you set up a trusted relationship with Identity Server. To manage 
these certificates in Administration Console, click Access Gateways > [Configuration Link] > 
Service Provider Certificates. For more information, see Section 15.3.1, “Managing Embedded 
Service Provider Certificates,” on page 968. 


+ Client browsers: You can enable SSL communication between the client browsers and Access 
Gateway. When setting up this feature, you can either have the Access Manager CA 
automatically generate a certificate key or you can select a certificate key you have already 
imported (or created) for the reverse proxy. To manage this certificate in Administration Console, 
click Access Gateways > [Configuration Link] > [Name of Reverse Proxy]. For more 
information, see Section 3.8.2, “Managing Reverse Proxies and Authentication,” on page 119. 


+ Protected Web servers: You can enable SSL communication between Access Gateway and 
the Web servers it is protecting. This option is only available if you have enabled SSL 
communication between the browsers and Access Gateway. You can enable SSL or mutual 
SSL. To manage these certificates in Administration Console, click Access Gateways > 
[Configuration Link] > [Name of Reverse Proxy] > [Name of Proxy Service] > Web Servers. For 
more information, see Section 3.8.3, “Configuring Web Servers of a Proxy Service,” on 
page 126. 


Assigning Certificates to Access Manager Devices 967 


15.3.1 


15.3.2 


Managing Embedded Service Provider Certificates 


Access Gateway uses an Embedded Service Provider to communicate with Identity Server. The 
Service Provider Certificates page allows you to view the private keys, certificate authority (CA) 
certificates, and certificate containers associated with this module. These keystores do not contain 
the certificates that Access Gateway uses for SSL connections to browsers or to back-end Web 
servers. 


To view or modify these certificates: 


1 In Administration Console Dashboard, click Devices > Access Gateways > Edit > Service 
Provider Certificates. 


2 Configure the following: 


Signing: The signing certificate keystore. Click this link to access the keystore and replace the 
signing certificate as necessary. The signing certificate is used to sign the logout requests from 
ESP to Identity Server. 


Trusted Roots: The trusted root certificate container for the CA certificates associated with 
Access Gateway. Click this link to access the trust store, where you can add trusted roots to the 
container. 


The Embedded Service Provider must trust the certificate of Identity Server that Access 
Gateway has been configured to trust. The public certificate of the CA that generated Identity 
Server certificate must be in this trust store. If you configured Identity Server to use a certificate 
generated by a CA other than the Access Manager CA, you must add the public certificate of this 
CA to the Trusted Roots store. To import this certificate, click Trusted Roots, then in the Trusted 
Roots section, click Auto-lmport From Server. Fill in the IP address or DNS name of your 
Identity Server and its port, then click OK. 


You can also auto import Identity Server certificate by selecting the Auto-Import Identity Server 
Configuration Trusted Root option on the Reverse Proxies / Authentication page (click Devices 
> Access Gateways > Edit > Reverse Proxies / Authentication). With this option, you do not 
need to specify the IP address and port of Identity Server. 


3 To save your changes to browser cache, click OK. 
4 To apply your changes, click the Access Gateways link, then click Update > OK. 


Managing Reverse Proxy and Web Server Certificates 


You select Access Gateway certificates on two pages in Administration Console: 


+ Devices > Access Gateways > Edit > [Name of Reverse Proxy] 


+ Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > 
Web Servers 


When you configure certificates on these pages, you need to be aware that two phases are used to 
push the certificates into active use. 


Phase 1: When you select a certificate on one of these pages, then click OK, the certificate is placed 
in the keystore on Administration Console and it is pushed to Access Gateway. The certificate is 
available for use, but it is not used until you update Access Gateway. 


Phase 2: When you select to update Access Gateway, the configuration for Access Gateway is 
modified to contain references to the new certificate and the configuration change is sent to Access 
Gateway. Access Gateway loads and uses the new certificate. 
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15.4 Changing a Non-Secure (HTTP) Environment to a 
Secure (HTTPS) Environment 


If you are running in a non-secure staging environment, and you’re ready to move to production, you 
must perform the following steps to enable security. 


1 Change Identity Server configuration protocol to HTTPS. (See Section 10.4, “Configuring Secure 
Communication on Identity Server,” on page 901.) 


2 Replace the test certificates with your own. (See Section 17.1.2, “Using Access Manager 
Certificates,” on page 978 or Section 17.1.3, “Using Externally Signed Certificates,” on 
page 980.) 


3 Update all devices that are trusting this Identity Server configuration. 
This causes the Embedded Service Provider to reimport the metadata of Identity Server. 


4 (Conditional) If you have set up federation, reimport metadata for trusted service and identity 
providers. (See Section 3.9.7, “Managing Metadata,” on page 189.) 


5 Change Access Gateway configuration to HTTPS. (See “Configuring Access Gateway for SSL” 
on page 980.) 
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16.1 


16.1.1 


Managing Trusted Roots and Trust 
Stores 


¢ Section 16.1, “Managing Trusted Roots and Trust Stores,” on page 971 
¢ Section 16.2, “Viewing External Trusted Roots,” on page 975 


Managing Trusted Roots and Trust Stores 


A certificate from a certificate authority (CA) is commonly referred to as trusted root. A trusted root is 
a trusted certificate, or the certificate of a known CA. These certificates are self-signed and are 
recognized as representing a CA that is trusted. To validate a digital signature, you must trust at least 
one of the certificates in the user or server’s certificate chain. You can directly trust the certificate of 
the user or server, or you can choose to trust any other certificate in the chain. Typically, the 
certificate that is trusted is the root CA's certificate. 


When an external certificate authority creates certificates, you need to import the trusted root of the 
certificate authority and assign the trusted root to the trust store of the device that needs to trust the 
certificate. 

1 In Administration Console Dashboard, click Security > Trusted Roots. 

2 Select form the following actions: 


Import: Allows you to import trusted roots so that Access Manager devices can trust the 
certificate sent by other computers at runtime. For more information, see Section 16.1.1, 
“Importing Public Key Certificates (Trusted Roots),” on page 971. 


Delete: To delete a trusted root, select the trusted root, then click Delete. 


Add Trusted Roots to Trust Stores: Allows you to assign a trusted root to a device so it can be 
used by that device. For more information, see Section 16.1.2, “Adding Trusted Roots to Trust 
Stores,” on page 972. 


Auto Import From Server: To import a trusted root from another server, click Auto Import From 
Server. For more information, see Section 16.1.3, “Auto-Importing Certificates from Servers,” on 
page 972. 


Importing Public Key Certificates (Trusted Roots) 


You import trusted roots so that the specific device can trust the certificate sent by other computers at 
runtime. After you import a trusted root, you can assign it to the proper trust store associated with a 
device, which allows the device to trust certificates signed by the trusted root. 
1 In Administration Console Dashboard, click Security > Trusted Roots. 
2 Click Import, then specify a name for the certificate. 
This is a system-wide, unique name used by Access Manager. 
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3 Select one of the following methods to import the public key: 


¢ Certificate data file (DER/PEM/PKCS7): Select this method to browse to a file. Click 
Browse to locate the file on your file system. 


+ Certificate data text (PEM/Base64): Select this method to paste Base64-encoded 
certificate data text. 


4 Click OK. 
5 Continue with “Adding Trusted Roots to Trust Stores” on page 972 


16.1.2 Adding Trusted Roots to Trust Stores 


After importing a trusted root, you need to assign it to a device before it is used by Access Manager. 


Run the /opt/novell/ag/bin/add_wellknownTR. sh script to add all well-known trusted roots to 
the proxy trust store automatically. 


To add a trusted root to an existing trust store manually, perform the following steps: 


1 In Administration Console Dashboard, click Security > Trusted Roots. 
2 Select the trusted root, then click Add Trusted Roots to Trust Stores. 
3 Fill in the following fields: 


Trusted roots: Select the trusted root store. To locate the trusted root store, click the Select 
Keystore icon. When you browse, the system displays the Select Trusted Roots page. Select the 
trusted root store, then click OK. 


Alias(es): Specify an alias for the trusted root. 
4 Click OK. 
5 Update the device that is using this trust store. 


16.1.3 Auto-Importing Certificates from Servers 


You can import certificates from other servers (such as an LDAP server, an identity provider, or 
service provider) and make them available for use in Access Manager. You must provide the IP 
address, port, and certificate name. 


1 In Administration Console Dashboard, click Security > Trusted Roots > Auto-Import from 
Server. 


2 Fill in the following fields: 
Server IP Address: Specify the server IP address. You can use a DNS name. 
Server Port: Specify the server port. 
Certificate Name: Specify a unique name of the certificate to store in Access Manager. 


3 Click OK. 


16.1.4 Exporting the Public Certificate of a Trusted Root 


You can export a trusted root or a public key certificate to a file so that a client can use it to verify the 
certificate chain sent by a cryptography-enabled application, or to have a backup copy of the file. 


You can export the certificate in the following formats: 


+ DER-encoded (.der) to a file. 
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+ PEM-encoded to a file. This is a Base64-encoded DER certificate that is enclosed between 
BEGIN CERTIFICATE and END CERTIFICATE tags. 


+ PEM CUT/Paste Buffer. This displays the certificate data so you can copy it to the system 
Clipboard. You can then pasted it directly into a cryptography-enabled application. 


To export the public certificate: 
1 In Administration Console Dashboard, click Security > Trusted Roots. 
2 Click the name of the trusted root. 


3 On the Certificate Details page, click Export Public Certificate, then click the file type. 
4 Save the output file. 


16.1.5 Viewing Trust Store Details 


1 In Administration Console Dashboard, click Security > Trusted Roots. 
2 Under the Devices column, click the name of a trust store. 


3 View the following information: 


Field Description 

Trust store name The name of the selected trust store. 

Trust store type The type of trust store, such as Java, PEM, or DER. 

Cluster of Device name The name of the cluster using this trust store or the single device 


that is using the trust store. 


Cluster Members’ Trust Stores The trust stores assigned to a cluster. If a device does not belong 
to a cluster, this section does not appear. 


Trusted Roots The trusted roots that are stored in the trust store. 
4 Click Close. 


16.1.6 Viewing Trusted Root Details 


1 In Administration Console Dashboard, click Security > Trusted Roots. 
2 Click the name of a trusted root. 
3 View the following information: 


Field Description 

Issuer The name of the CA that created the certificate. 

Serial number The serial number of the certificate. 

Subject The subject name of the certificate. 

Valid from The first date and time that the certificate is valid. 

Valid to The date and time that the certificate expires. 

Devices The devices that are configured to hold this certificate on their file 
system. 
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Field Description 


Key size The key size that was used to create the certificate. 
Signature algorithm The signature algorithm that was used to create the certificate. 
Finger print (MD5) The certificate's message digest that was calculated with the MD5 


algorithm. It is embedded into the certificate at creation time. It can 
be used to uniquely identify a certificate. For example, users can 
verify that a certificate is the one they think it is by matching this 
published MD5 fingerprint with the MD5 fingerprint on the local 
certificate. 


Finger print (SHA256) The certificate's message digest that was calculated with the SHA- 
256 algorithm. It is embedded into the certificate at creation time. It 
can be used to uniquely identify a certificate. For example, users 
can verify that a certificate is the one they think it is by matching a 
published SHA-256 fingerprint with the SHA-256 fingerprint on the 
local certificate. 


The Subject Alternate Names section indicates whether an application should reject the 
certificate if the application does not understand the alternate name extensions. Any configured 
alternate names are displayed in the list. 


The Key Usage section indicates whether an application should reject the certificate if the 
application does not understand the key usage extensions. The following are possible: 


Sign CRLs: Indicates whether the certificate is used to sign CRLs (Certificate Revocation Lists). 
Sign certificates: Indicates that the certificate is used to sign other certificates. 
Encrypt other keys: Indicates that the certificate is used to encrypt keys. 


Encrypt data directly: Indicates that the certificate encrypts data for private transmission to the 
key pair owner. Only the intended receiver can read the data. 


Create digital signatures: Indicates that the certificate is used to create digital signatures. 


Non-repudiation: Indicates that the certificate links a digital signature to the signer and the data. 
This prevents others from duplicating the signature because no one else has the signer’s private 
key. Additionally, the signer cannot deny having signed the data. 


CRL Distribution Points: Displays a list of Certificate Revocation List (CRL) distribution points 
that are embedded into the certificate as an extension at certificate creation time. 
Implementations search the CRL from each distribution point (the distribution point is usually a 
URI that points to a store of revoked certificates) to see whether a certificate has been revoked. 


Authority Info Access (OCSP): Displays a list of Online Certificate Status Protocol (OCSP) 
responders that are embedded into the certificate as an extension at certificate creation time. 
Implementations query the OCSP responder to see whether a certificate has been revoked. 


Select from the following actions: 


Export Public Certificate: Allows you to export a trusted root to a file so that a client can use it 
to verify the certificate chain sent by a cryptography-enabled application. For more information, 
see Section 14.5, “Exporting a Public Certificate,” on page 959. 


Add Trusted Root to Trust Stores: Allows you to assign a trusted root to a device so it can be 
used by that device. For more information, see Section 16.1.2, “Adding Trusted Roots to Trust 
Stores,” on page 972 


5 Click Close. 
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Viewing External Trusted Roots 


Identity Server uses local Access Manager CA and external certificate authorities to verify the SSL 
certificates. The external certificates are listed in the External Trusted Roots tab. 


NOTE: All the well-known trusted roots are added to the proxy trust store during the Access Manager 


Installation. 


1 Click Security > Trusted Roots > External Trusted Roots. 


The External Trusted Roots tab lists all the external trusted roots that Access Manager supports. 


2 View the following information: 


Field 


Alias 


Issuer 
Subject 
Starting Date 


Ending Date 


Description 


The name of the certificate as seen by the Access Manager 
appliance. 


The name of the CA that created the certificate. 
The subject name of the certificate. 
The date and time from which the certificate is valid. 


The date and time till that the certificate is valid. 
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[ Enabling SSL Communication 


¢ Section 17.1, “Enabling SSL Communication,” on page 977 
¢ Section 17.2, “Using SSL on Access Gateway Communication Channels,” on page 990 


¢ Section 17.3, “Configuring SSL for Authentication between Identity Server and Access Manager 
Components,” on page 992 


¢ Section 17.4, “Prerequisites for SSL,” on page 992 


¢ Section 17.5, “Configuring SSL Communication with Browsers and Access Gateway,” on 
page 993 


¢ Section 17.6, “Configuring SSL between the Proxy Service and the Web Servers,” on page 995 
¢ Section 17.7, “Configuring the SSL Communication,” on page 996 


17.1 Enabling SSL Communication 


Because Identity Server handles authentication, it must be configured for SSL before any of the other 
Access Manager components. You can then configure Access Gateway to use SSL in its connections 
to Identity Server, to the browsers, and to its Web servers. 

¢ Section 17.1.1, “Identifying the SSL Communication Channels,” on page 978 

¢ Section 17.1.2, “Using Access Manager Certificates,” on page 978 

e Section 17.1.3, “Using Externally Signed Certificates,” on page 980 

¢ Section 17.1.4, “Using an SSL Terminator,” on page 985 

¢ Section 17.1.5, “SSL Renegotiation,” on page 988 
SSL impacts the performance of Access Manager components. Instead of enabling Access Manager 
components for SSL, you can front the components with an SSL terminator or accelerator. The SSL 
terminator offloads the handling of the SSL traffic, and the Access Manager components can be 


configured to use HTTP. For some tips on using such a device, see Section 17.1.4, “Using an SSL 
Terminator,” on page 985. 


Enabling SSL Communication 977 


17.1.1 


17.1.2 


Identifying the SSL Communication Channels 


Access Manager has five communication channels that you can configure for SSL. Figure 17-1 
illustrates these channels. 


Figure 17-1 Potential SSL Communication Channels 
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The first channel is set between Identity Server and LDAP servers when you configure user stores 
(see step 4 in Section 3.3, “Configuring an Identity Server,” on page 59). The other channels need to 
be configured according to their numeric values. You need to configure SSL between Identity Server 
and browsers before you configure the channel between Access Gateway and Identity Server for 
SSL. 


eDirectory that resides on Administration Console is the main certificate store for all Access Manager 
components. You can use this local certificate authority (CA) to create certificates for SSL or you can 
purchase certificates from a well-known certificate authority. This section describes how to use both 
types of certificates to enable secure communication. 

¢ Section 17.1.2, “Using Access Manager Certificates,” on page 978 


¢ Section 17.1.3, “Using Externally Signed Certificates,” on page 980 


Using Access Manager Certificates 


By default, all Access Manager components (Identity Server and Access Gateway) trust the local CA. 
However, the browsers are not set up to trust the Access Manager CA. You need to import the public 
key of the trusted root certificate (configCA) into the browsers to establish the trust. 


This section discusses the following procedures: 


¢ Section 17.1.2.1, “Configuring Secure Communication on Identity Server,” on page 979 


¢ Section 17.1.2.2, “Configuring Access Gateway for SSL,” on page 980 
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17.1.2.1 Configuring Secure Communication on Identity Server 


Identity Server comes with a the test-connector certificate. This procedure shows you how to replace 
this certificate by completing the following tasks: 

¢ Enable SSL on Identity Server (changing from HTTP to HTTPS) 

e Create a certificate 

e Replace the test-connector certificate with the newly created certificate 


To configure SSL on Identity Server: 


1 Click Devices > Identity Servers. 
2 In the Configuration column, click Edit. 


3 Change Protocol to HTTPS (the system changes the port to 8443), click Apply, then click OK at 
the warning. 


4 Copy the domain name of your Identity Server configuration to the clipboard, or take note of the 
name. It must match the common name of the new certificate. 


5 Click the SSL Certificate icon, then click OK at the warning if you clicked Apply when you 
changed the protocol to HTTPS. 


If you did not click Apply, then click Cancel and click Apply before returning to this option 
The Keystore configuration page appears. 

In the Certificates section, click Replace. 

In the Replace dialog box, click the Select Certificate icon next to the Certificate field. 
On the Select Certificate page, click New. 


Oo ON 


Click Use local certificate authority. 


This option creates a certificate signed by the local CA (or Organizational CA), and creates the 
private key. 


10 Fill in the following fields: 


Certificate name: A name that you can associate with this certificate. For easy reference, you 
might want to paste the domain name of Identity Server configuration in this field. 


For information about how to modify the default values before clicking OK, see Section 13, 
“Creating Certificates,” on page 947. 


Subject: Click the Edit Subject icon. In the Common Name field, paste the domain name of the 
base URL of Identity Server configuration. This value cannot be an IP address or begin with a 
number, to ensure that trust does not fail between providers. 


If you are going to be using Windows CardSpace, fill in values for the other common attributes. 
11 Click OK. 
12 To accept the default values in the other fields, click OK twice. 
The new certificate is displayed on the Select Certificate page. 
13 Verify that the new certificate is selected, then click OK. 
14 Click OK on the Replace dialog box. 
15 Click Restart Now to restart Tomcat, as prompted. 
16 Click Close on the Keystore page. 


+ If your Identity Server and Administration Console are on the same machine, you need to 
log in to Administration Console again. 


+ If your Identity Server is on another machine, click OK. 
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17.1.3 


17.1.3.1 


17 To verify the health of Identity Server, click Devices > Identity Servers. 


18 To update the embedded service provider of Access Gateway to use the new URL, click Devices 
> Access Gateways > Update. 


If you do not receive the option to update Access Gateway, select Access Gateway, then click 
Actions > Service Provider > Restart Service Provider > OK. 


Restarting the service provider reestablishes the trust between Access Gateway and the new 
base URL for Identity Server. 


19 Verify that the trusted relationship between Identity Server and Access Gateway has been 
reestablished. 


19a Enter the URL to a protected resource on Access Gateway. 
19b Complete one of the following: 


¢ If you can access the site, the trusted relationship has been reestablished. Continue 
with “Configuring Access Gateway for SSL” on page 980. 


+ If you receive a 100101043 or 100101044 error, the trusted relationship has not been 
established. For information about how to solve this problem, see Section 30.3.2, 
“Troubleshooting 100101043 and 100101044 Liberty Metadata Load Errors,” on 
page 1196. 


Configuring Access Gateway for SSL 


See the following topics: 
¢ Section 17.5, “Configuring SSL Communication with Browsers and Access Gateway,” on 
page 993 
¢ Section 17.6, “Configuring SSL between the Proxy Service and the Web Servers,” on page 995 


Using Externally Signed Certificates 


When Identity Server is configured to use an SSL certificate that is signed externally, the trusted store 
of the embedded service provider for each component must be configured to trust this new CA. The 
browsers that are used to authenticate to Identity Server must be configured to trust the CA that 
created the certificate for Identity Server. If you obtain a certificate from a well-known external CA, 
most browsers are already configured to trust certificates from well-known CAs. 


The following procedures explain how to use certificates signed by an external Certificate Authority. 


¢ Section 17.1.3.1, “Obtaining Externally Signed Certificates,” on page 980 


¢ Section 17.1.3.2, “Configuring Identity Server to Use an Externally Signed Certificate,” on 
page 983 


¢ Section 17.1.3.3, “Configuring Access Gateway to Use an Externally Signed Certificate,” on 
page 984 
Obtaining Externally Signed Certificates 


The following sections explain how to create certificate signing requests for Identity Server and 
Access Gateway, how to use the requests to obtain signed certificates, then how to import the signed 
certificates and the root certificate of the Certificate Authority into Access Manager. 


¢ “Creating the Certificate Signing Request” on page 981 
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“Getting a Signed Certificate” on page 982 
“Importing the Signed Certificates and Root Certificate” on page 982 


Creating the Certificate Signing Request 


You need to create two certificate signing requests: one for Identity Server and one for Access 
Gateway. The Certificate name and the Common name need to be different, but the other values can 


be the same. 
What you need to know or create Example Your Value 
Certificate name ipda_test or lag_test 


Certificate Subject Fields: 


Common name ipda.test.novell.com or 
lag.test.novell.com 


Organizational unit novell 
Organization test 
City or town Provo 
State or province UTAH 
Country US 


To create a signing request for Identity Server: 


1 


Click Security > Certificates > New. 


2 Select the Use External certificate authority option. 


3 Specify the following details: 


Certificate name: idpa_test 

Signature algorithm: Accept the default. 
Valid from: Accept the default. 

Months valid: Accept the default. 

Key size: Accept the default. 


4 Click the Edit icon on the Subject line. 


5 Specify the following details: 


Common name: idpa.test.novell.com 
Organizational unit: novell 

Organization: test 

City or town: Provo 

State or province: UTAH 

Country: US 

Click OK twice, then click the name of the certificate. 


7 Click Export CSR. 


The signing request is saved to a file. 
Repeat Step 1 through Step 7 to create a signing request for Access Gateway. 
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Getting a Signed Certificate 


Send the certificate signing request to a certificate authority and wait for the CA to return a signed 
certificate or you can use a trial certificate for testing while you wait for the official certificate. 
Companies such as VeriSign offer trial signed certificates for testing. 


Modify the following instructions for the CA you have selected to sign your certificates: 


Bh WN RF 


Set up an account with a certificate authority and select the free trial option. 
Open your certificate signing request for Identity Server in a text editor. 
Copy and paste the text of the certificate request into the appropriate box for a trial certificate. 


If CA requires that you select a server platform, select eDirectory if available. If eDirectory is not 
a choice, select unknown or server not listed. 


Click Next, then copy the signed certificate and paste it into a new text file or at the bottom of the 
signing request file. 


Click Back, and repeat Step 2 through Step 5 for Access Gateway. 


7 Follow the instructions of the vendor to download the root certificate of the Certificate Authority 


and any intermediate CA certificates. 


Importing the Signed Certificates and Root Certificate 


The following steps explain how to imported the signed certificates and the trust root into 
Administration Console so that they are available to be assigned to key stores and trusted root stores. 


1 


Click Security > Trusted Roots. 


2 Click Import, then specify a name for the root certificate. 


3 Either click Browse and locate the root certificate file or select Certificate data text and paste the 


o ON OO UO 


10 


12 


13 


certificate in the text box. 

Click OK. 

The trusted root is added and is now available to add to trusted root stores. 

(Conditional) Repeat Step 2 through Step 4 for any intermediate CA certificates. 

In a text editor, open the signed certificate for Identity Server. 

Click Security > Certificates, then click the name of certificate signing request for Identity Server. 
Click Import Signed Certificate, then select Certificate data text (PEM/Based64). 

Paste the text for the signed certificate into the data text box. Copy everything from 

-----BEGIN CERTIFICATE----- 

through 


Click Add trusted root, then either click Browse and locate the root certificate file or select 
Certificate data text and paste the certificate in the text box. 


(Conditional) For any intermediate CA certificates, click Add intermediate certificate, then either 
click Browse and locate the intermediate certificate file or select Certificate data text and paste 
the certificate in the text box. 


Click OK. 
The certificate is now available to be assigned to the keystore of a device. 
Repeat Step 6 through Step 12 for Access Gateway certificate. 
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NOTE: If the certificate fails to import and you receive an error, it is probably missing a trusted root 
certificate in a chain of trusted roots. To determine whether this is the problem, see “Resolving a - 
1226 PKI Error” on page 1223 and “Importing an External Certificate Key Pair” on page 1222. 


Configuring Identity Server to Use an Externally Signed Certificate 


This section explains how to enable SSL between Identity Servers and browsers. 


1 


Click Devices > Identity Servers > Edit. 


2 Change Protocol to HTTPS (the system changes the port to 8443). 


3 In the SSL Certificate line, click the Browse icon > Replace and select the Identity Server 


7 


certificate. 
Restart Tomcat. 


If your Identity Server and Administration Console are on the same machine, log in to 
Administration Console again. 


After the Identity Server health turns green, go to Access Gateway > Edit > Service Provider 
Certificates > Trusted Roots. 


Click Add to select the trusted root certificate of the certificate authority that signed Identity 
Server certificate. 


(Conditional) If you imported intermediate certificates for the CA, select them also. 


IMPORTANT: If the external certificate authority writes the DN in reverse order (the cn element 
is displayed first), you receive an error message that the certificate names do not match. You 
can ignore this warning, if the order of the DN elements is the cause. 


Update Access Gateway. 


To test the SSL connection between the browser and Identity Server: 


1 


2 


3 


Enter the Base URL of Identity Server in a browser. 
https://idpa.test.novell.com:8443/nidp 


If the URL returns a login page, log in using the credentials of a user in the LDAP server. 
The user portal appears. 
If the URL returns an error rather than displaying a login page, verify the following: 

+ The browser trusts the CA that created the certificate. 

+ The browser can resolve the DNS name of Identity Server 

+ The browser can access port 8443. 


Verify that the trusted relationship between Identity Server and Access Gateway has been 
reestablished. 


3a Enter the URL to a protected resource on Access Gateway. 
3b Complete one of the following: 


¢ If you are prompted for login credentials, enter them. The trusted relationship has been 
reestablished. 
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¢ If you receive a 100101043 or 100101044 error, the trusted relationship has not been 
established. 


For information about solving this problem, see Section 30.3.2, “Troubleshooting 
100101043 and 100101044 Liberty Metadata Load Errors,” on page 1196. 


17.1.3.3 Configuring Access Gateway to Use an Externally Signed Certificate 


This section explains how to enable SSL communication between Access Gateway and Identity 
Server (channel 3 in Figure 17-1 on page 978). 
1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 


2 Select Enable SSL with Embedded Service Provider and Enable SSL between Browser and 
Access Gateway. 


3 In the Server Certificate line, click the Browse icon to select Access Gateway certificate. 


IMPORTANT: If the external certificate authority writes the DN in reverse order (the cn element 
comes first rather than last), you receive an error message that the subject name does not 
contain the cn of the device. You can ignore this warning, if the order of the DN elements is the 
cause. 


4 Click Auto-Import Embedded Service Provider Trusted Root. 


This adds the trusted root of Access Gateway certificate to the trusted root store of Identity 
Server. 


5 Specify an Alias for the certificate. 
6 On the Server Configuration page, click Reverse Proxy / Authentication. 


7 In the Embedded Service Provider section, click Auto-Import Identity Server Configuration 
Trusted Root and follow the prompts. 


This imports the trusted root certificate of Identity Server into the trusted root store of the 
embedded service provider. 


8 Update Access Gateway and Identity Server on respective pages. 
To verify the trusted relationship between Identity Server and Access Gateway: 


1 Enter the URL to a protected resource on Access Gateway. 
2 Complete one of the following: 


+ If you are prompted for login credentials, enter them. The trusted relationship has been 
reestablished. 


+ If you receive a 100101043 or 100101044 error, the trusted relationship has not been 
established. 


For information about solving this problem, Section 30.3.2, “Troubleshooting 100101043 
and 100101044 Liberty Metadata Load Errors,” on page 1196. 
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17.1.4 Using an SSL Terminator 


An SSL terminator is a method of offloading the processor-intensive public key encryption algorithms 
involved in SSL transactions to a hardware terminator or accelerator. This can be a separate card that 
plugs into a PCI slot in a computer that contains one or more coprocessors able to handle the SSL 
processing, or it can be a dedicated (and expensive) hardware device. 


The most processing-intensive part of an SSL session is the stage where the SSL server (Identity 
Server or Access Gateway) is required to decrypt the SSL session key (an asymmetric key) that has 
been sent to it from the SSL client (usually a Web browser). This is known as the SSL handshake. 
Typically a hardware SSL terminator offloads the processing of the SSL handshake while leaving the 
server software to process the less intense symmetric cryptography of the actual SSL data exchange. 
The terminator can also act as a proxy and handle all SSL operations, which allows the server that is 
behind the terminator use unencrypted connections. 


The performance benefits to the Access Manager servers are very high, often resulting in faster 
performance and higher throughput. 


Although the Access Manager configuration settings are the same for any SSL terminator, the 
process for configuring the terminator for rewriting varies with the hardware. The following 
explanations use the Citrix Netscaler SSL terminator to explain the required rewriter configuration. 
For more information about this SSL terminator, see the following documents: 


¢ Citrix NetScaler Traffic Management Guide was used for general information about the device. 
¢ SharePoint Deployment Guide was used for the actual setup of the SSL terminator. 


The following sections describe the required network configuration, the required Access Manager 
components, and the terminator and Access Gateway configuration process. 


¢ Section 17.1.4.1, “Required Setup,” on page 985 
¢ Section 17.1.4.2, “Configuring the SSL Terminator,” on page 986 
¢ Section 17.1.4.3, “Configuring Access Gateway,” on page 987 


17.1.4.1 Required Setup 
The following diagram illustrates the sample setup that was used for the configuration steps. 
Identity Servers 
Load Balancer a 
and 
SSL Terminator 


https Ea http 


Access Gateways 


a 


Web Servers 


a 


| 
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This setup has the following features: 


+ 


The Citrix Netscaler SSL terminator is configured to load balance (it provides the L4 switch 
functionality) and to offload the SSL traffic. 


Identity Servers and Access Gateways are accessible only through the SSL terminator via HTTP. 
Identity Servers and Access Gateways communicate to each other through the SSL terminator. 


Identity Server cluster is configured to use HTTP on port 80. For information about translating 
the default 8080 port to 80, see Translating the Identity Server Configuration Port in the NetIQ 
Access Manager 4.3 Installation and Upgrade Guide. 


Configuring the SSL Terminator 


The configuration instructions assume that the SSL virtual servers have been created for Access 


Gateways and Identity Servers on the SSL terminator. This sample configuration uses the logical 
name of “Access Manager Access Gateway” for Access Gateway virtual server, and “Access 
Manager Identity Server” for the Identity Sever virtual server. The virtual server setup details are 


available in the documentation links referenced in Section 17.1.4, “Using an SSL Terminator,” on 


page 985. 


1 


2 


To enable the rewrite functionality: 


Configure the SSL terminator to rewrite information in the HTTP header to be HTTPS: 


The string used within the quotes is the virtual server name of the SSL virtual server. Each 
Access Manager component set has a different name for the virtual server. 


1a At the command line, enter the following command for Access Gateway: 


set ssl vserver "Access Manager Access Gateway" -sslRedirect ENABLED - 
redirectPortRewrite ENABLED 


The "Access Manager Access Gateway" string needs to be replaced with the name you 
have specified for Access Gateway virtual server. 


Enabling SSL Redirect (-ss1Redirect) causes the SSL terminator to convert any HTTP 
302 redirect responses from back-end servers to HTTPS redirects. 


1b At the command line, enter the following command for Identity Server. 


set ssl vserver "Access Manager Identity Server" -sslRedirect ENABLED - 
redirectPortRewrite ENABLED 


The "Access Manager Identity Server" string needs to be replaced with the name you 
have specified for Identity Server virtual server. 


Create a policy to scan the HTTP data (as opposed to headers) as it passes through the SSL 
terminator and replace references to http:// with references to https://. 


At the command line, enter the following commands: 


add rewrite action httpRewriteAction replace_all "http.res.body(50000)" 
"\"https://\"" -pattern "http://" 


add rewrite policy HttpToHttpsRewrite "http.res.body(50000).contains(\"http:// 
\")" httpRewriteAction 


The (50000) value references the number of bytes to scan. This number can be tweaked for the 
size of the page; 50000 was from the Citrix support examples. 

Bind the policy to Identity Server virtual server. 

At the command line, enter the following command: 
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bind 1b vserver "Access Manager Identity Server" -policyName HttpToHttpsRewrite 
-priority 100 -gotoPriorityExpression END -type RESPONSE 


This command rewrites all Identity Server generated references of http to the https scheme. 
For example, the following entry in the default login (login. jsp) page includes an HTML form 
with an action tag that indicates where the credentials are to be posted. The page includes the 
following line: 


<form name="IDPLogin" enctype="application/x-www-form-urlencoded" 
method="POST" action="<%= (String) request.getAttribute("url") %>" 
AUTOCOMPLETE="0ff"> 


When the JSP is executed, the following is sent back to the browser by Identity Server: 


<form name="IDPLogin" enctype="application/x-www-form-urlencoded" 
method="POST" action="http://idp126.1lab.novell.com/nidp/idff/sso?sid=4" 
AUTOCOMPLETE="0ff"> 


With the policy defined above, the action tag is rewritten to the following: 


<form name="IDPLogin" enctype="application/x-www-form-urlencoded" 
method="POST" action="https://idp126.1lab.novell.com/nidp/idff/sso?sid=4" 
AUTOCOMPLETE="0ff"> 


Configuring Access Gateway 


With the SSL terminator rewriting HTTP to HTTPS for Identity Server, the only changes required on 
the Access Manager side are for Access Gateway. There are three particular cases where Access 
Gateway must have its scheme rewritten: 


+ All Web pages rendered through Access Gateway must have their schemes rewritten from HTTP 
to HTTPS. 


Because of the complexity of Web pages, many SSL terminators have issues rewriting all 
references in a Web page from HTTP to HTTPS. Access Gateway must take responsibility for 
this work. 


By default, Access Gateway rewriter does not rewrite the scheme if the proxy service and back- 
end Web servers use the same protocol. In this case, all traffic into the proxy is HTTP and all 
traffic to the back-end Web servers is also HTTP, which implies that no scheme rewriting takes 
place. Because the browser expects all links to reference HTTPS schemes, Access Gateway 
must be configured to automatically rewrite all HTTP references on Web pages to HTTPS. 


+ The Liberty Authentication request generated by Access Gateway must have the target URL 
rewritten to HTTPS. 


When a user accesses an Access Gateway protected resource, a corresponding Liberty 
authentication request is generated by the Embedded Service Provider and is sent to Identity 
Server via the browser. This authentication request includes multiple attributes, including 
information about the trusted Liberty service provider generating the request, a target URL 
where the user must be redirected to post authentication, and the contract to be executed at 
Identity Server. The target URL is embedded in this authentication request and references an 
HTTP resource. Access Gateway must be able to rewrite this HTTP request to HTTPS. The 
following example was sent by Access Gateway to Identity Server via the browser. 
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HTTP/1.1 302 Moved Temporarily 

Server: Apache-Coyote/1.1 

Set-Cookie: JSESSIONID=AF5484F1CD4D218C5404A17AQDA86E5A; Path=/nesp; secure 
Location: http://idp126.lab.novell.com/nidp/idff/ 

sso?Request ID=idQgvQqocG6fgFrkeiUG6j1RD.LMk&MajorVersion=1&MinorVersion=2&Issu 
eInstant=2010-05- 

18T13%3A53%3A26Z&ProviderID=ht tps%3A%2F%2Flag129.lab.novell.com%3A443%2Fnesp%2 
Fidff%2Fmetadata&RelayStat e=MA%3D%3D&consent=urn%3Aliber ty%3Aconsent%3Aunavail 
able&ForceAuthn=false&IsPassive=false&NameIDPolicy=onetime&ProtocolProfile=htt 
p%3A%2F%2Fprojectliberty.org%2Fprofiles%2Fbrws - 
art&target=http%3A%2F%2Flag129.lab.novell.com%3A443%2Fformfil1l%2Fphpinfo.phpen 
tRef=u&AuthnContextStatemscel1%2Fsecure%2Fname%2Fpassword%2Furi 

Date: Tue, 18 May 2010 13:53:26 GMT 

Content-Length: 0 

Via: 1.1 lagi29.lab.novell.com (Access Gateway 3.1.1-265_eng_600589- 
7AA324FFCBA4D4ED ) 


The target parameter embedded within the authentication request references HTTP in the 
following line: 


http%3A%2F%2Flagi29.lab.novell.com%3A443%2Fformfill%2Fphpinfo.php 
This needs to be rewritten to use the HTTPS scheme, for example: 
https%3A%2F%2Flag129.lab.novell.com%3A443%2Fformfill%2Fphpinfo.php 

+ The Location HTTP header in the 302 redirects must have its scheme rewritten from HTTP to 


HTTPS. There are two cases where Access Gateway sends 302 redirects back to the browser: 


+ When a non-authenticated user tries to access a protected resource, a series of HTTP 
redirects are generated by Access Gateway that redirect the user to the Embedded Service 
Provider or to Identity Server server requesting the user’s credentials. Browsers execute on 
these 302 redirect status codes and generate corresponding requests to the URL defined in 
the Location HTTP header. The scheme on the Location header must be HTTPS and not 
the default HTTP. 


+ When the back-end Web server sends a 302 redirect to the browser, Access Gateway must 
interpret the URL and make any rewrites it deems necessary (such as scheme and path- 
based multi-homing path injection). Because the proxy and back-end Web server schemes 
are both HTTP in the setup, the Location header is not rewritten by default. 


The Location header rewriting is handled by the SSL terminator. You have already enabled this 
rewriting in Step 1a on page 986. 


To configure Access Gateway to rewrite Web page references and the target URL: 
1 Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication. 


2 In the Proxy Settings section, select Behind Third Party SSL Terminator, then click OK. 
3 Click OK, then update Access Gateway. 


SSL Renegotiation 


SSL renegotiation is the process of establishing a new SSL handshake over an existing SSL 
connection. SSL renegotiation can be initiated either by the SSL client or the SSL server. Initiating an 
SSL renegotiation on the client or the server requires different set of APIs. The renegotiation 
messages (ciphers and encryption keys) are encrypted and then sent over the existing SSL 
connection to establish another session securely and is useful in the following scenarios: 


+ When you require a client authentication. 
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+ When you require a different set of encryption and decryption keys. 
+ When you require a different set of encryption and hashing algorithms. 


SSL renegotiation is enabled or disabled by the following parameter: 
"sun.security.ssl.allowUnsafeRenegotiation. 


NOTE: By default, this parameter is disabled. 


This is defined in a registry on Windows and a configuration file on SLES. 


You can verify whether Identity Server, Access Gateway and Administration Console support secure 
renegotiation by using the following command: 


openssl s_client -connect <IP address of the Access Manager component: port> 


Port can either be 8443 or 443 based on Access Gateway configuration. 


Enabling a Windows SSL Renegotiation 


Perform the following steps to enable the SSL renegotiation on Windows 64-bit platform: 


1 Launch Registry Editor by executing the Start > Run regedit command. 


2 In the left pane of Registry Editor, navigate to My Computer > 
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Apache Software Foundation\Procrun 
2.0\Tomcat7\Parameters\Java\. 


3 Double-click Options in the right pane of the Registry Editor. 
4 Search for the -Dsun.security.ssl.allowUnsafeRenegotiation string. 


+ If -Dsun.security.ssl.allowUnsafeRenegotiation is available, set the value to true. 
For example, -Dsun.security.ssl.allowUnsafeRenegotiation=true 


+ If -Dsun.security.ssl.allowUnsafeRenegotiation is not available, add - 
Dsun.security.ssl.allowUnsafeRenegotiation=true 


5 Goto C:\Program Files(x86)\Novell\Tomcat\conf\server.xml > Server > Service > 
Connector, then search for the connector 8443 and check if the connector has the port 8443. 


6 Add the allowUnsafeLegacyRenegotiation=true string. 
7 Restart Tomcat to enable the SSL renegotiation. 


Perform the following steps to enable the SSL renegotiation on Windows 32-bit platform: 


1 Launch Registry Editor by executing the command regedit in Start > Run. 


2 Inthe left pane of Registry Editor, navigate to My Computer > 
HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 
2.0\Tomcat7\Parameters\Java\. 


3 Double-click Options in the right pane of registry editor. 
4 Search for the -Dsun.security.ssl.allowUnsafeRenegotiation string. 


+ If -Dsun.security.ssl.allowUnsafeRenegotiation is available, set the value to true. 
For example, -Dsun.security.ssl.allowUnsafeRenegotiation=true. 


+ If -Dsun.security.ssl.allowUnsafeRenegotiation is not available, add 
-Dsun.security.ssl.allowUnsafeRenegotiation=true. 


5 Goto C:\Program Files(x86)\Novell\Tomcat\conf\server.xml > Server > Service > 
Connector., then search for the connector 8443 and check if the connector has the port 8443. 
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6 Add the allowUnsafeLegacyRenegotiation=true string. 

7 Restart Tomcat to enable the SSL renegotiation. 
The following instructions explain how to disable the SSL renegotiation in Windows 32- bit and 
Windows 64-bit platform: 

1 Launch Registry Editor by executing the command regedit in Start > Run. 


2 In the left pane of Registry Editor, navigate to My Computer > 
HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 
2.0\Tomcat7\Parameters\Java\. 


3 Double-click Options in the right pane of registry editor. 
4 Search for the -Dsun.security.ssl.allowUnsafeRenegotiation string. 


5 In -Dsun.security.ssl.allowUnsafeRenegotiation, set the value to false. For example, - 
Dsun.security.ssl.allowUnsafeRenegotiation=false 


6 Restart Tomcat to disable the SSL renegotiation. 


Enabling a Linux SSL Renegotiation 


To enable the SSL renegotiation on SLES 11 SP2 and SP3, add the parameter 
JAVA_OPTS="${JAVA_OPTS} -Dsun.security.ssl.allowUnsafeRenegotiation=true in the 
configuration file /var/opt/novell/tomcat7/conf/tomcat7.conf if the parameter does not exist. 


Restart Tomcat to enable SSL renegotiation. 


To disable the SSL renegotiation on SLES 11 SP2 and SP3, add the parameter 
JAVA_OPTS="${JAVA_OPTS} -Dsun.security.ssl.allowUnsafeRenegotiation=false in the 
configuration file /var/opt/novell/tomcat7/conf/tomcat7.conf if the parameter does not 
exist if the parameter does not exist. 


Restart Tomcat to disable SSL renegotiation. 


Using SSL on Access Gateway Communication 
Channels 


You can configure Access Gateway to use SSL in its connections to Identity Server, to the browsers, 
and to its Web servers. Figure 17-2 illustrates these communication channels. 
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Figure 17-2 Setting Up SSL for Access Gateway Communication Channels 
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This section only describes how to set up SSL for Access Gateway communication channels. Identity 
Server needs to be configured for SSL before Access Gateway can be configured for SSL. See 
“Configuring Secure Communication on Identity Server” on page 979. 


When a user logs in to Identity Server, Identity Server verifies the user’s credentials, usually with the 
credentials stored in an LDAP directory, but other methods are available. If the login is successful, 
Identity Server sends an artifact to the browser, and the browser forwards it to Access Gateway. 
Access Gateway uses the artifact to retrieve the user's name and password from Identity Server. 
Access Gateway and Identity Server channel is probably the first communication channel you should 
enable for SSL. Access Gateway uses an Embedded Service Provider to communicate with Identity 
Server. When you enable SSL between the two, the Access Manager distributes the necessary 
certificates to set up SSL. However, if you have configured Identity Server to use certificates from an 
external certificate authority (CA), you need to import the public certificate of this CA into the trust 
store of Access Gateway. If you have set up Access Gateway to use a certificate from an external CA, 
you need to import the public certificate of this CA into the trust store of Identity Server. 


SSL must be enabled between Access Gateway and the browsers before you can enable SSL 
between Access Gateway and its Web servers. If you enable SSL between Access Gateway and the 
browsers, SSL is automatically enabled for Access Gateway Embedded Service Provider that 
communicates with Identity Server. After you have enabled SSL between Access Gateway and the 
browsers, you can select whether to enable SSL between Access Gateway and the Web servers. By 
not enabling SSL to the Web servers, you can save processing overhead if the data on the Web 
servers is not sensitive or if it is already sufficiently protected. 


Whether you need the added security of SSL or mutual SSL between Access Gateway and its Web 
servers depends upon how you have set up your Web servers. 


+ You should enable at least SSL if Access Gateway is injecting authentication credentials into 
HTTP headers. 


¢ Mutual SSL is probably not needed if you have configured the Web servers so that they can only 
accept connections with Access Gateway. 
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Configuring SSL for Authentication between 
Identity Server and Access Manager Components 


By default, all Access Manager components (Identity Server and Access Gateway) trust the 
certificates signed by the local CA. However, if Identity Server is configured to use an SSL certificate 
signed externally, the trusted store of the service provider for Access Gateway must be configured to 
trust this new CA. Import the public certificate of the CA into the following trust store: 


For an Access Gateway, click Devices > Access Gateways > Edit > Service Provider Certificates > 
Trusted Roots. 


If an Access Gateway is configured to use an SSL certificate signed externally, the trusted store of 
Identity Server must be configured to trust this new CA. Import the public certificate of the CA into 
Identity Server configuration that the component is using for authentication. 


Click Devices >Identity Servers > Edit > Security > NIDP Trust Store and add the certificate to the 
Trusted Roots list. 


NOTE: Whenever you replace certificates on a device, you must update Identity Server configuration 
(by clicking Update Servers on the Servers page), or restart Embedded Service Provider. 


Prerequisites for SSL 


The following SSL configuration instructions assume that you have already created or imported the 
certificate that you are going to use for SSL. This certificate must have a subject name (cn) that 
matches the published DNS name of the proxy service that you are going to use for authentication. 
You can obtain this certificate one of two ways: 


+ You can use the Access Manager CA to create this certificate. See Section 13.1, “Creating a 
Locally Signed Certificate,” on page 948. 


+ You can create a certificate signing request (CSR), send it to an external CA, then import the 
returned certificates into Access Manager. See Section 13.4, “Generating a Certificate Signing 
Request,” on page 952 and Section 16.1.1, “Importing Public Key Certificates (Trusted Roots),” 
on page 971. 


Prerequisites for SSL Communication between Identity 
Server and Access Gateway 


If you are going to set up SSL communication between Identity Server and Access Gateway for 
authentication and you have configured Identity Server to use certificates created by an external CA, 
you need to import the public certificate of this CA into the trusted root keystore of Access Gateway. 


1 If you have not imported the public certificate of this CA into the trusted root store of Identity 
Server, do so now. For more information, see Section 16.1.1, “Importing Public Key Certificates 
(Trusted Roots),” on page 971. 


2 To add the public certificate to Access Gateway: 
2a Click Devices > Access Gateways > Edit > Service Provider Certificates > Trusted Roots 
2b In the Trusted Roots section, click Add. 
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2c Click the Select trusted root(s) icon, select the public certificate of the CA that signed 
Identity Server certificates, then click OK. 


2d Specify an alias, then click OK twice. 
3 To apply the changes, click Close, then click Update on the Access Gateways page. 


Prerequisites for SSL Communication between Access 
Gateway and Web Servers 


If you are going to set up SSL between Access Gateway and the Web servers, you need to configure 
your Web servers for SSL. Your Web servers must supply a certificate that clients (in this case, 
Access Gateway) can import. See your Web server documentation for information about how to 
configure the Web server for SSL. 


For mutual SSL, the proxy service must supply a certificate that the Web server can trust. This 
certificate can be the same one you use for SSL between the browsers and the reverse proxy. 


Configuring SSL Communication with Browsers 
and Access Gateway 


This section explains how to enable SSL communication between Access Gateway and the browsers 
(channel 4 in Figure 17-1 on page 978). 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 
2 Configure the reverse proxy for SSL by filling in the following fields: 


Enable SSL with Embedded Service Provider: Select this option to encrypt the data 
exchanged for authentication (the communication channel between Identity Server and Access 
Gateway). This option is available only for the reverse proxy that has been assigned to perform 
authentication. 


If you enable SSL between the browsers and Access Gateway, this option is automatically 
selected for you. You can enable SSL with the Embedded Service Provider without enabling SSL 
between Access Gateway and the browsers. This allows the authentication and identity 
information that Access Gateway and Identity Server exchange to use a secure channel, but 
allows the data that Access Gateways retrieves from the back-end Web servers and sends to 
users to use a non-secure channel. This saves processing overhead if the data on the Web 
servers is not sensitive. 


Enable SSL between Browser and Access Gateway: Select this option to require SSL 
connections between your clients and Access Gateway. SSL must be configured between the 
browsers and Access Gateway before you can configure SSL between Access Gateway and the 
Web servers. 


Redirect Requests from Non-Secure Port to Secure Port: Determines whether browsers are 
redirected to the secure port and allowed to establish an SSL connection. If this option is not 
selected, browsers that connect to the non-secure port are denied service. 


This option is only available if you have selected Enable SSL with Embedded Service Provider. 


3 Select the certificate to use for SSL between Access Gateway and browsers. Select one of the 
following methods: 


+ To auto-generate a certificate key by using the Access Manager CA, click Auto-generate 
Key, then click OK twice. The generated certificate appears in the Server Certificate text 
box. 
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The generated certificate uses the published DNS name of the first proxy service for the 
Subject name of the certificate. If there is more than one proxy service, the CA generates a 
wildcard certificate (*.Cookie Domain). 


If you have not created a proxy service for this reverse proxy, wait until you have created a 
proxy service before generating the key. This allows the CN in the Subject field of the 
certificate to match the published DNS name of the proxy service. 


+ To select a certificate, click the Select Certificate icon, select the certificate you have 
created for the DNS name of your proxy service, then click OK. The certificate appears in 
the Server Certificate text box. For SSL to work, the CN in the Subject field of the certificate 
must match the published DNS name of the proxy service. 


4 (Conditional) If you selected a certificate in Step 3 that was created by an external CA, click 


Auto-Import Embedded Service Provider Trusted Root, click OK, specify an alias name, click 
OK, then click Close. 


This option imports the public key from the Embedded Service Provider into the trust store of 
Identity Servers in the selected Identity Server Configuration. This sets up a trusted SSL 
relationship between Identity Server and the Embedded Service Provider. 


If you are using certificates signed by the Access Manager CA, the public key is automatically 
added to this trust store. 


Configure the ports for SSL: 


Non-Secure Port: Specifies the port on which to listen for HTTP requests. The default port for 
HTTP is 80. 


+ If you selected the Redirect Requests from Non-Secure Port to Secure Port option, 
requests sent to this port are redirected to the secure port. If the browser can establish an 
SSL connection, the session continues on the secure port. If the browser cannot establish 
an SSL connection, the session is terminated. 


+ Ifyou do not select the Redirect Requests from Non-Secure Port to Secure Port option, this 
port is not used when SSL is enabled. 


IMPORTANT: If you select not to redirect HTTP requests (port 80) and your Access Gateway 
has only one IP address, do not use port 80 to configure another reverse proxy. Although it is not 
used, it is reserved for this reverse proxy. 


Secure Port: Specifies the port on which to listen for HTTPS requests (usually 443). This port 
needs to match the configuration for SSL. If SSL is enabled, this port is used for all 
communication with the browsers. The listening address and port combination must not match 
any combination you have configured for another reverse proxy or tunnel. 


Click OK. 
On the Configuration page, click Reverse Proxy / Authentication. 


(Conditional) If you are using an externally signed certificate for Identity Server cluster, you need 
to import the public key of the CA: 


8a In the Embedded Service Provider section, click Auto-Import Identity Server Trusted Root, 
then click OK. 


8b Specify an alias, click OK twice, then click Close. 
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This option imports the public key of Identity Server into the trust store of the Embedded 
Service Provider. This sets up a trusted SSL relationship between the Embedded Service 
Provider and Identity Server. 


The configCA public key certificate of the Access Manager CA is automatically added to the 
ESP Trust Store. If you are using Access Manager CA certificates for Identity Server, you do 
not need to import the configCA certificate unless someone has deleted it from this trust 
store. 


9 Click OK. 
10 On the Server Configuration page, click OK. 
11 OnAccess Gateways page, click Update > OK. 
The Embedded Service Provider is restarted during the update. 


12 Update Identity Server so that it uses the new SSL configuration. Click Identity Servers > 
Update. 


13 Verify that the trusted relationship between Identity Server and Access Gateway has been 
reestablished. 


13a Enter the URL to a protected resource on Access Gateway. 
13b Complete one of the following: 


¢ If you are prompted for login credentials, enter them. The trusted relationship has been 
reestablished. 


¢ If you receive a 100101043 or 100101044 error, the trusted relationship has not been 
established. For information about how to solve this problem, see Section , 
“Troubleshooting 100101043 and 100101044 Liberty Metadata Load Errors,” on 
page 1137. 


Configuring SSL between the Proxy Service and 
the Web Servers 


SSL must be enabled between Access Gateway and browsers before you can enable it between 
Access Gateway and its web servers. See Section 17.5, “Configuring SSL Communication with 
Browsers and Access Gateway,” on page 993. 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> Web Servers. 
2 Select Connect Using SSL. 
3 Configure how you want the proxy service to verify the web server certificate: 
3a Select one of the following options in Web Server Trusted Root: 


Do not verify: Use this option when you want the information between Access Gateway and 
the web server encrypted, but you do not need the added security of verifying the web 
server certificate. 

Continue with Step 4. 


Any in Reverse Proxy Trust Store: Use this option to verify the certificate authority of the 
web server certificate. When this option is selected, the public certificate of the certificate 
authority must be added to the proxy trust store. 
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3b 
3c 


3d 


IMPORTANT: For an Access Gateway Service, this is a global option. If you select this 
option for one proxy service, all proxy services on an Access Gateway Service are flagged 
to verify the public certificate. This verification is done even when other proxy services are 
set to Do not verify. 


If the web server certificate is part of a chain of certificates, select SSLProxyVerifyDepth 
and specify how many certificates are in the chain. 


The SSL connection between Access Gateway and a web server may fail if a self-signed 
certificate is used. To prevent this, import the web server certificates to the proxy trust store 
and then use the following advanced option: 


Windows: SSLProxyCACertificateFile "C:\Program 
Files\Novell\apache\cacerts\myserver.pem", 


Linux: SSLProxyCACertificateFile /opt/novell/apache2/cacerts/myserver. pem. 
This is a service level advanced option. 


Click Manage Reverse Proxy Trust Store. 


Ensure that the IP address of the web server and the port match your web server 
configuration and then click OK. 


If the whole chain is not displayed, import what is displayed. You then need to manually 
import the missing parents in the chain. A parent is missing if the chain does not include a 
certificate where the Subject and the Issuer have the same CN. 


Specify an alias. 
All the displayed certificates are added to the trust store. 


4 (Optional) Set up mutual authentication so that the web server can verify the proxy service 


certificate. Click Select Certificate to select the certificate you created for the reverse proxy. 


You need to import the trusted root certificate of the CA that signed the proxy service's certificate 
to the web servers assigned to this proxy service. For instructions, see your Web server 
documentation. 


5 In Connect Port, specify the port that your web server uses for SSL communication. 


Configuring the SSL Communication 


By default, Access Manger supports the 128-bit SSL communication among Administration Console, 
Identity Server, and browsers. It is recommended to enable strong ciphers. 


For the list of 256-bit ciphers, see Java ™ Cryptography Architecture Oracle Providers 
Documentation. 


To enable strong 256-bit or higher ciphers: 


1 Open the server.xml] file. 


Linux: /opt/novell/nam/adminconsole/conf/ 
Windows Server 2012: \Program Files (x86)\Novell\Tomcat\conf 


2 Add the 256-bit ciphers to the cipher attribute of <Connectors>. 


For example, 
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<Connector NIDP_Name="connector" port="2443" maxHttpHeaderSize="8192" 
maxThreads="200" minSpareThreads="5" enableLookups="false" 
disableUploadTimeout="true" acceptCount="0" scheme="https" secure="true" 
clientAuth="false" sslProtocol="tls" URIEncoding="UTF-8" 
allowUnsafeLegacyRenegotiation="false" keystoreFile="/var/opt/novell/novlwww/ 
.keystore" keystorePass="changeit" SSLEnabled="true" address="164.99.87.129" 
ciphers="SSL_RSA_WITH_RC4_128 MD5, SSL_RSA_WITH_RC4_128 SHA, 

TLS_RSA_WITH_AES_ 128 CBC_SHA, TLS _DHE_RSA_WITH_AES_128 CBC_SHA, 
TLS_DHE_DSS_WITH_AES_128 CBC_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA, 
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA" /> 
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Analytics Dashboard 


Analytics Dashboard provides visual analytics of access related data based on the usage, 
performance, and events of Access Manager. The events are captured and filtered through Analytics 
Server. For more information about Analytics Server, see Section 1.3.4, “Analytics Server,” on 

page 37. 


This dashboard helps in visualizing the access patterns, tuning the policies and getting insights about 
the usage of Access Manager in your environment. You can also monitor the real-time data access 
patterns to decide further actions. 


The Analytics dashboard displays the following graphs by default. You can customize the layout of 


the dashboard based on your requirements. 


+ 


+ 


Access Gateway Accessed Applications 


Access Gateway Active Users 
Access Gateway Cache Utilization 
Access Gateway Logins 

Access Gateway Requests 
Access Gateway Uptime 

Access Gateway Clusters 

Access Gateways 

Geolocation of Users Logged In 
Identity Server Accessed Applications 
Identity Server Active Users 
Identity Server Logins 

Identity Server Clusters 

Identity Servers 

Most Used Browsers 

Most Used Endpoint Devices 
Post-Auth Risk Distribution 
Pre-Auth Risk Distribution 

Unique Users Logged In 


18.1 Advantages of Using Analytics Dashboard 


¢ Displays visual analytics based on access patterns, logins, risk-based authentication, and usage 
of Access Manager. This helps the administrators to tune the system according to their needs. 


+ The trends of using devices, browsers, or applications in an organization. 


¢ |t provides the number of unique users who are logged in to Access Manager. 
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¢ It displays the graphs in a full screen (kiosk) mode, which helps in viewing Analytics Dashboard 
in a data center. Also, it does not time-out. 


¢ It can display a snapshot of the historic data graphs based on the query for any specific time 
period. 


18.2 Architecture 


Analytics dashboard uses Analytics Server to filter the events that are required for generating graphs. 
The following diagram displays the architecture of Analytics dashboard. 


Access Manager 
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Analytics Server Analytics Dashboard 
Administrator with Administrator with 
limited access to full access to 
Administration Console Administration Console 


The data flow for Analytics Server is as follows: 


1. The Access Manager components generate events based on user access. 


2. The generated events are sent to Analytics Server real-time aggregator, which analyses and 
stores the event details for 7 days. 


3. The historic data is forwarded to offline aggregator. 


This saves the historic data of the generated events that is no longer available in real-time 
aggregator. 


4. Data from the real-time aggregator is displayed in the form of graphs in the Analytics Dashboard. 


You can view the historic data graphs in Analytics Dashboard by retrieving data from the offline 
aggregator by using the Scheduler page. 


18.3 Who Can Access Analytics Dashboard 


All the Access Manager administrators and any other users who are added in the configuration store 
of Administration Console can access Analytics Dashboard. They can view and manage Analytics 
Dashboard. 


NOTE: The policy container administrators (delegated administrators and policy view administrators) 
do not have access to Analytics Dashboard. 
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To create a user in the configuration store perform the following: 
1 In Administration Console, click <user name> at the top right of the page and then click Manage 
Roles & Tasks > Users > Create User. 
2 Specify the details in the mandatory fields. 
3 Context: Specify the organization context. This is a mandatory field. 


3a Click object selector icon. The object selector browser displays the Browse and Search 
tabs. 


3b Click Browse tab. Select novell option from the Contents list. 
4 Password: Specify the password and retype the password to confirm it. 
Failure to enter a password will allow the user to login without a password. 


NOTE: This user can access only Analytics Dashboard and does not have the rights to make 
changes in Administration Console. 


18.4 Prerequisites 


To view the required data in Analytics Dashboard, ensure that you perform the following before 
launching it: 


1. Install Analytics Server. For information about installation, see the NetIQ Access Manager 4.3 
Installation and Upgrade Guide. 


2. Configure the settings on Administration Console. For more information about configuration 
settings, see Section 4.5, “Analytics Server Configuration,” on page 349 


3. On Administration Console, click Auditing then select Send to Analytics Server in the Audit 
Messages Using: field and specify the primary server’s IP address. For more information, see 
Section 19.1.1, “Specifying the Logging Server and Console Events,” on page 1017. 


4. Enable the events for the required graphs. For more information about the events required for 
each graph, see Section 18.5, “Enabling Events for Each Graph,” on page 1003. 


5. (Conditional) If you want any specific user to view Analytics Dashboard, then add the user to the 
configuration store. For more information about adding the user to configuration store, see 
Section 18.3, “Who Can Access Analytics Dashboard,” on page 1002. 


18.5 Enabling Events for Each Graph 


To view each graph on Analytics Dashboard you must enable the required events in Administration 
Console. The events that are enabled are sent to Analytics Server, which generates graphs for 
Analytics Dashboard. 


NOTE: If the events are not enabled, the graphs do not display any data. 


To view the events for Identity Server, perform the following on Administration Console: 


1 Click Devices > [Identity Server cluster name] > Edit > Auditing and Logging. 


2 In the Audit Logging section, select Enabled. 


To view the events for Access Gateway, click Devices > [Access Gateway server] > Edit > Auditing 
on Administration Console: 
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The following table provides the list of graphs with the required events: 


Graph 


Unique Users Logged In 


+ 


Identity Server Active Users 

+ Access Gateway Active Users 

+ Access Gateway Uptime 

+ Access Gateway Requests Trend 


+ Access Gateway Cache Utilization 


Access Gateway Accessed Applications 


Access Gateway Logins 


Identity Server Accessed Applications 


Identity Server Logins 


Pre Auth Risk Distribution 


Post Auth Risk Distribution 


Geolocation of Users Logged In 


+ Most Used Browsers 


+ Most Used Endpoint Devices 


Most accessed users (from 4.3 SP1 onwards) 
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Events 


+ 


+ 


Logins Consumed (Identity Server) 


Session Created/ Destroyed (Access Gateway) 


Server Statistics 


+ 


Session Created/ Destroyed 


+ Application Accessed 


Session Created/ Destroyed 


+ 


+ 


+ 


+ 


Federation Token Sent 
Federation Token Received 
Token Issued to Web Service 


OAuth and OpenID token Issued 


Logins Consumed 


Risk Based Pre-authentication Action Invoked (Identity 
Server) 


Risk-based Authentication Action Invoked (Identity 
Server) 


+ 


+ 


+ 


Logins Consumed (Identity Server) 
Session Created/ Destroyed (Access Gateway) 


Risk Based Pre-authentication Action Invoked 
(Identity Server) 


Risk-based Authentication Action Invoked 
(Identity Server) 

Session Created/ Destroyed (Access Gateway) 
Logins Consumed (Identity Server) 


Risk Based Pre-authentication Action Invoked 
(Identity Server) 


Risk-based Authentication Action Invoked 
(Identity Server) 


Risk-based Authentication Action Invoked (If risk- 
based authentication is configured) 


Risk Based Pre-authentication Action Invoked (If 
risk-based authentication is configured) 


Logins Consumed (Identity Server) 


18.6 


18.6.1 


Graph Events 
Client IP Addresses (from 4.3 SP1 onwards) + Risk-based Authentication Action Invoked (If risk- 
based authentication is configured) 


+ Risk Based Pre-authentication Action Invoked (If 
risk-based authentication is configured) 


+ Login Consumed 
+ Login Consumed Failure 
Most Used Contracts (from 4.3 SP1 onwards) + Login Consumed 
+ Login Consumed Failure 
Failed Authentications (from 4.3 SP1 onwards) + Login Consumed Failure 
¢ Identity Server Clusters Not required. Health information is directly fetched 


from Administration Console. 
+ Identity Server ene 


+ Access Gateway Clusters 


+ Access Gateway 


Viewing Data in Analytics Dashboard 


Analytics Dashboard displays all the required Access Manager events in the form of graphs. You can 
view data in each graph only if the events are enabled for the graphs. For information about enabling 
events for each graph, see Section 18.5, “Enabling Events for Each Graph,” on page 1003. The 
graphs are displayed based on the default data query and in the following modes: 


¢ Section 18.6.1, “Real-time Data,” on page 1005 
¢ Section 18.6.2, “Historic Data,” on page 1006 


Real-time Data 


By default, the real-time data mode displays the graphs with data for the last 7 days. 


You can add filters, or refresh the data after a specific time duration. You can view data from the time 
Analytics Server is configured till the present time, but the data that is older than 7 days will not be 
displayed. 


For more information about applying time-filters, see Section 18.9.5, “Adding/ Modifying Refresh 
Time for Real-time Dashboard,” on page 1013. 


For information about the actions that you can perform on a dashboard, see Section 18.9, “Managing 
Analytics Dashboard,” on page 1010 
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18.6.2 Historic Data 


The historic data mode displays the graphs based on the older events that are stored in offline 
aggregator. The data is displayed for the time duration that administrator specifies in the Analytics 
Dashboard scheduler. 


When an administrator requires the historic data, they can specify the duration in the Scheduler page, 
then Analytics Server generates an analytic graph report that is used for displaying the graphs with 
historic data. The Administrator can delete the data manually or specify the duration after which the 
analytic report must be deleted from the scheduler. 


You can view these graphs from the Scheduler screen. For more information about using Scheduler, 
see Section 18.9.6, “Viewing Historic Data,” on page 1014. 


To return to the default dashboard to view the real-time data, you can click the Goto saved default 
icon. For information about the actions that you can perform on the dashboard, see Section 18.9, 
“Managing Analytics Dashboard,” on page 1010. 


18.7 Types of Graphs 


The graphs represent information about the business requirement of an organization that uses 
Access Manager to secure its applications. The Analytics Dashboard displays the following graphs in 
real-time and historic data modes by default: 

¢ Section 18.7.1, “Unique Users Logged In,” on page 1007 

e Section 18.7.2, “Identity Server Active Users,” on page 1007 

¢ Section 18.7.3, “Access Gateway Active Users,” on page 1007 

¢ Section 18.7.4, “Geolocation of Users Logged In,” on page 1007 

¢ Section 18.7.5, “Pre-Auth Risk Distribution,” on page 1007 

¢ Section 18.7.6, “Post-Auth Risk Distribution,” on page 1008 

¢ Section 18.7.7, “Identity Server Accessed Applications,” on page 1008 

¢ Section 18.7.8, “Access Gateway Accessed Applications,” on page 1008 

¢ Section 18.7.9, “Most Used Browsers,” on page 1008 

¢ Section 18.7.10, “Most Used Endpoint Devices,” on page 1008 

¢ Section 18.7.11, “Most Accessed Users (Available from 4.3 SP1 Onwards),” on page 1008 

¢ Section 18.7.12, “Client IP Addresses (Available from 4.3 SP1 Onwards),” on page 1008 

¢ Section 18.7.13, “Most Used Contracts (Available from 4.3 SP1 Onwards),” on page 1009 

¢ Section 18.7.14, “Failed Authentications (Available from 4.3 SP1 Onwards),” on page 1009 

¢ Section 18.7.15, “Identity Server Logins,” on page 1009 

¢ Section 18.7.16, “Access Gateway Logins,” on page 1009 

¢ Section 18.7.17, “Access Gateway Uptime,” on page 1009 

¢ Section 18.7.18, “Access Gateway Requests,” on page 1009 

¢ Section 18.7.19, “Access Gateway Cache Utilization,” on page 1009 

¢ Section 18.7.20, “Identity Server Clusters,” on page 1009 

¢ Section 18.7.21, “Identity Servers,” on page 1010 

¢ Section 18.7.22, “Access Gateway Clusters,” on page 1010 

¢ Section 18.7.23, “Access Gateways,” on page 1010 
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18.7.1 


18.7.2 


18.7.3 


18.7.4 


18.7.5 


Unique Users Logged In 


This graph displays the user count based on the number of distinct users who are logged in to Identity 
Server and Access Gateway. This count is irrespective of how often they send log in requests. 


This graph helps to determine the number of distinct users who are logged in to web applications that 
are configured to use Access Manager. 


Identity Server Active Users 


This graph displays the data for the number of users who are logged in to Identity Server and is active 
at a specific interval. 


This graph is helpful in analysing how many users are authenticated within a specific time interval. 


Access Gateway Active Users 


This graph displays the data for the number of users who are logged in to Access Gateway server 
and is active within a specific time interval. 


This graph is helpful in determining how many users are authorized within a specific time interval. 


Geolocation of Users Logged In 


This displays the map with number of logged in users in specific geographical location. You can hover 
the mouse on each region to know the number of users who are accessing applications from that 
region. 


To view this graph you must configure the geographical location. For information about configuring 
the geolocation, see Section 4.5.5, “Configuring Analytics Server,” on page 353. 


This graph helps in identifying the location from where the most or the least number of users access 
applications. 


NOTE: To display the user count for different countries, Analytics Server uses the IP address that is 
specified in the geolocation provider database. Hence, the data on the graph is dependent on the 
configured geolocation provider details. 


Pre-Auth Risk Distribution 


This graph displays a pie-chart with the distribution of the levels of risk (high, medium, and low). Each 
portion displays the risk percentage based on the number of sessions and percentage of the risk level 
that is configured in Identity Server. 


These graphs help in determining the risks that are detected before authentication. Based on the risk 
level, administrators can change the policies to mitigate the risk. 
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18.7.6 


18.7.7 


18.7.8 


18.7.9 


18.7.10 


18.7.11 


18.7.12 


Post-Auth Risk Distribution 


This graph displays the pie-chart with the different levels of risk (high, medium, and low). Each portion 
of the pie-chart displays the risk percentage based on the number of sessions and percentage of the 
risk level that is configured in Identity Server. 


These graphs help in mitigating the risk that are detected after authentication. 


Identity Server Accessed Applications 


This graph displays the name and the number of times the applications such as, federated 
applications, OAuth, and WS-Trust are accessed through Identity Server. 


This graph helps in determining the most commonly used applications through Identity Server. 


Access Gateway Accessed Applications 


This graph displays the name of web applications with the number of times any web application is 
accessed through Access Gateway. 


This graph helps in determining the most commonly used applications through Access Gateway. 


Most Used Browsers 


This graph displays the name of all the browsers with the comparison of their usage in Access 
Manager environment. 


This graph helps in determining the most commonly used browsers from which the requests are sent 
to applications that are configured with Access Manager. 


Most Used Endpoint Devices 


This graph displays the name of all the endpoint devices with the comparison of their usage in the 
Access Manager environment. 


This graph helps in determining the most commonly used devices that users use for sending access 
requests. 


Most Accessed Users (Available from 4.3 SP1 Onwards) 


This graph displays the name of the top ten users who have got access by using Access Manager. 
Other includes the names of other users. 


This graph helps in determining the users who frequently send requests to get access through 
Access manager. 


Client IP Addresses (Available from 4.3 SP1 Onwards) 


This graph displays the IP address of the client machines from which the requests are received 
frequently. 
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18.7.13 


18.7.14 


18.7.15 


18.7.16 


18.7.17 


18.7.18 


18.7.19 


18.7.20 


Most Used Contracts (Available from 4.3 SP1 Onwards) 


This graph displays the name and number of the frequently used contracts. 


This graph helps in determining the most commonly used contracts that is used for authentication. 


Failed Authentications (Available from 4.3 SP1 Onwards) 


This graph displays the number of failed authentications that occurred in a specific interval. 


Identity Server Logins 


This graph displays the number of login requests that are sent to Identity Server with respect to time. 


This graph helps in determining the interval when there are too many user login requests sent to 
Identity Server. 


Access Gateway Logins 


This graph displays the number of login requests that are sent to Access Gateway with respect to 
time. 


This graph helps in determining the interval when there are too many user login requests sent to 
Access Gateway. 


Access Gateway Uptime 


This graph displays the total time Access Gateway has been running since it was last started. 


It helps in determining the time for next reboot. 


Access Gateway Requests 


This graph displays the number of requests that are sent to Access Gateway at a specific interval. 


This graph helps in determining the load on Access Gateway server at each interval. 


Access Gateway Cache Utilization 


This graph displays the percentage of the used cache from the available cache for Access Gateway. 


Identity Server Clusters 


This graph displays all Identity Server clusters with the health of each cluster. You can view the health 
statistics based on the number of nodes that are active at a specific time period. 


You can also disable a cluster and view Analytics Dashboard without using data from that cluster. 
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18.7.21 


18.7.22 


18.7.23 


18.8 


18.9 


Identity Servers 


This graph displays the list of all Identity Server machines with the health of each server. 


You can disable data filter for any required Identity Server and view Analytics Dashboard without the 
data that is generated from those servers. 


Access Gateway Clusters 


This graph displays all Access Gateway clusters with the health of each cluster. You can view the 
health statistics based on the number of nodes that are active at a specific time period. 


You can also disable a cluster and view Analytics Dashboard without using data from that cluster. 


Access Gateways 


This graph displays the list of all Access Gateway servers with the health of each server. 


You can disable data filter for any required Access Gateway servers and view Analytics Dashboard 
without the data that is generated from those servers. 


Accessing Analytics Dashboard 


You can access Analytics Dashboard by using any of the following ways: 


+ Administration Console Dashboard: You can access Analytics Dashboard from 
Administration Console either by clicking Devices > Analytics Server > Analytics Dashboard or 
by clicking Analytics Dashboard under Admin Tasks. 


+ Analytics Dashboard Web page: You can directly access the webpage by using the following 
URL: 


https://<ip address of Analytics Server>:8445/amdashboard/login 


NOTE: Ensure that you have installed and configured Analytics server. For information about 
Analytics Server configuration refer Section 4.5, “Analytics Server Configuration,” on page 349. 


If you are using Analytics Server in high availability mode, you must enable the Page Reload 
option. If one of the nodes fail when accessing a dashboard, then Analytics Server prompts for 
re-authentication. For information about Page Reload, see Section 18.9.5, “Adding/ Modifying 
Refresh Time for Real-time Dashboard,” on page 1013. 


Managing Analytics Dashboard 


Analytics Dashboard is the default dashboard. You cannot save changes to Analytics Dashboard, 
but you can modify it and save it with a different name. You can create different dashboards as per 
your requirements. The points on the line graphs is plotted based on the highest number that is 
reached in the duration of 5 minutes. 
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18.9.1 


18.9.2 


Access Manager Dashboard 


| Eoo 


Creating a new graph, or modifying any query is not supported. Hence, you must not modify the 
default settings of the graphs and dashboard. But, you can perform the following to manage 
dashboards: 


peres APPLICATIONS o © + x ACCESS GATEWAY ACCESSED APPLICATIONS o0o® Oo + x 


¢ Section 18.9.1, “Managing Layout of the Dashboard,” on page 1011 

¢ Section 18.9.2, “Exporting and Importing a Customized Dashboard,” on page 1011 

¢ Section 18.9.3, “Filtering Data to View Required Details,” on page 1012 

¢ Section 18.9.4, “Managing Dashboard,” on page 1012 

¢ Section 18.9.5, “Adding/ Modifying Refresh Time for Real-time Dashboard,” on page 1013 
¢ Section 18.9.6, “Viewing Historic Data,” on page 1014 


Managing Layout of the Dashboard 
You can customize the layout of a dashboard by dragging and dropping required graphs as per your 


requirements. You can also delete the unused graphs and save the dashboard with the changes. 


You can perform the following to save a customized dashboard: 
1 (Conditional) If you want to change the positioning of each graph click on the drag icon +, then 
move the graphs at the required positions. 
2 (Conditional) If you want to remove unused graphs, close each unused graphs. 
3 Click the Save icon. 
4 Specify a name for the customized dashboard. 
5 Click the Save icon on the left. 


Exporting and Importing a Customized Dashboard 


You can export the required customized dashboard to any location on the system, then import it when 
you require it. 
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18.9.2.1 


18.9.2.2 


18.9.3 


18.9.4 


Exporting a Customized Dashboard 
1 Log in to Analytics Dashboard 


2 Click the Load iconic, then select the customized dashboard that you require to export 


3 Click the Save icon 
4 Click Advanced > Export schema 
5 Click Save > Browse to save the file to the required location 


Importing a Customized Dashboard 
1 Log in to Analytics Dashboard 


2 Click the Load icone 

3 Click Import schema 

4 Click Choose File to browse to the correct location, then select the required dashboard file 
5 Save the imported dashboard 


Filtering Data to View Required Details 


You can choose to view the required details by adding filters to the data that generates the graphs. 
Filters are the queries that are generated when you select a section of a graph. 


When you add a filter for one graph, it is applied to all the graphs in the dashboard. For example, if 
you select a specific time range in the Identity Server Active Users graph, all the graphs will display 
the data based on the same time range. In the same way, whenever you select the level of risk, 
geolocation, or specific interval within a graph, all graphs display data based on the selected level of 
risk, location, or time respectively. 


You can view the filters under the Filtering tab of a dashboard. If you have applied too many filters, 
then you can revert back to the required filter by removing the filters from the Filtering tab. 


Managing Dashboard 
An administrator can specify any action, which is a query that runs in the back end of the dashboard. 


You can view or delete the query by using the Filtering tab. This section covers the actions that you 
can perform on Analytics dashboard. 


Table 18-1 Managing dashboards 


Action Icon Description 

Goto Saved Default | # | To load any of the customized 
dashboards that is saved as the 
default dashboard. 

Load G To search for saved dashboards or 


remove any dashboard from the list. 
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18.9.5 


Action Icon Description 


Default Dashboard E To load the default Analytics 
dashboard. You cannot modify/ 
delete this dashboard, but you can 
customize this dashboard by saving 
it with a different name. 


Save 7 To save the customized dashboard. 
You can also save the dashboard 
as default by clicking Advanced > 
Save as Home. 


` 


To share the dashboard URL with 
other administrators. 


Share 


Configure Dashboard | | To modify the dashboard settings 
as per the requirement. 


Note: You must not change the 
default settings of the dashboard 
because Access Manager does not 
support Analytics Dashboard with 
changed settings. 


Analytics Scheduler To generate a report for a specified 
schedule and to view the graphs 
when the report is generated. 


You can also delete the report from 
scheduler. 


Adding/ Modifying Refresh Time for Real-time Dashboard 


The real-time dashboard displays the last 7 days data by default. You can select the appropriate time 
frame from the Time filter field. For example, if you want to view only the data from last 24 hours, then 
select Time filter > Last 24h. 


You can also specify the auto-refresh duration in the Time filter field, which will refresh the dashboard 
with the latest data after the specified duration. For example, if you want the dashboard to refresh the 
graphs after every 5 minutes, you can select Time filter > Auto-Refresh > 5m. You can also manually 
refresh the graphs whenever it is required. 


If you are using Analytics Server in a high-availability mode or using dashboard for prolonged 
monitoring, ensure that you select Time filter > Auto-Refresh > Page Reload > Every 10m. 


NOTE: If the Auto-Refresh option is off, the dashboard will time-out based on the time-out setting of 
Administration Console. 


It is recommended to use the Page Reload option to minimize the memory usage on the browser. You 
must disable the Page Reload option whenever you are modifying or saving the dashboard otherwise 
your changes will be lost. To disable this option click Time filter > Auto-Refresh > Page Reload > Off. 
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18.9.6 Viewing Historic Data 


The Scheduler page helps in generating reports for Analytics Dashboard from the older events that 
are stored in the Analytics Server database. This report is used only for generating graphs on 
Analytics Dashboard. 


When you require to retrieve data from the database for a specific duration, the scheduler analyses 
the historic data, then generates a report for Analytics Dashboard. 


To create report for historic data, you must use the scheduler page. This page helps with the 
following: 
¢ View the details of previously scheduled graphs. 


+ Specify the time range, data availability (in days, after which the graphs will be auto deleted) for 
a new report for Analytics Dashboard. 


+ Check the status of the report (scheduled, inprogress, completed). 
¢ Click on the completed analytic reports to view the graphs. 
+ Delete the graphs. 


To view the historic data, you must perform the following on Analytics dashboard: 


1 Click the scheduler icon to view the Analytics Scheduler screen. 


2 (Conditional) If you want scheduler to analyze the events that were generated during a specific 
duration, specify the following under Schedule New Analysis: 


+ Time Range: Click to select the start and the end date of the historic data. 


+ Keep Data For: Click to select the period till when you want the report to be available under 
the Analysed Data Available list. 


3 (Conditional) If you have already scheduled analysis for generating reports, then to view the 
graphs, click the graph icon next to the report with Status as Completed under Analyzed Data 
Available. 


It may take some time for the scheduler to retrieve the data and analyze it for generating the 
report. 


NOTE: When you launch a dashboard with the historic data, you must not remove data filters 
under the Filtering tab. If the filter is removed, the graphs will not display the data for the time 
range that was specified. 
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Q Auditing 


NOTE: Platform Agent and Novell Audit are no longer supported. A new Access Manager 4.2 
installation no longer installs Platform Agent and Novell Audit for auditing. If you upgrade from an 
older version of Access Manager to 4.2, Platform Agent is still available. It is recommended to use 
Syslog for auditing. 


Access Manager supports audit logging and file logging at the component level. Access Manager 
provides compliance assurance logging and to maintain audit log entries that can be subsequently 
included in reports. In addition to selectable events, device-generated alerts are automatically sent to 
the audit server. You can configure Access Manager to use a Sentinel server, a third party syslog 
server, or use Analytics Server. 


The audit logs record events that have occurred in the identity and access management system and 
are primarily intended for auditing and compliance purposes. You can configure the following types of 
events for logging: 

¢ Starting, stopping, and configuring a component 

¢ Success or failure of user authentication 

+ Role assignment 

+ Allowed or denied access to a protected resource 

+ Error events 

+ Denial of service attacks 

¢ Security violations and other events necessary for verifying the correct and expected operation 

of the identity and access management system 


Audit logging does not track the operational processing of the Access Manager components; that is, 
the processing and interactions between Access Manager components required to fulfill a user 
request. (For this type of logging, see Section 21.3.1, “Configuring Logging for Identity Server,” on 
page 1038.) Audit logs record the results of user and administrator requests and other system events. 
Although the primary purpose for audit logging is for auditing and compliance, you can also use the 
event logs for detecting abnormal and error conditions. The event logs can be used as a first alert 
mechanism for system support. 


Access Manager has been assigned the server-alert event code 0x002E0605. It is responsible for 
packaging and forwarding audit log entries to the configured audit server. 


For a secure system, you need to configure auditing and syslog to notify the system administrator 
when certain events occur. The most important audit events to monitor are the following: 


¢ Configuration changes 

Ħ System shutdowns and startups 

+ Server imports and deletes 

¢ Intruder lockout detection (available only for eDirectory user stores) 


¢ User account provisioning 
Audit events are device-specific. You can select events for the following devices: 


¢ Administration Console: In Administration Console Dashboard, click Auditing. 
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¢ Identity Server: Click Devices > Identity Servers > Edit > Auditing and Logging. 
+ Access Gateway: Click Devices > Access Gateways > Edit > Auditing. 


This section discusses the following topics: 


¢ Section 19.1, “Enabling Auditing,” on page 1016 
e Section 19.2, “Enabling Identity Server Audit Events,” on page 1021 
¢ Section 19.3, “Enabling Access Gateway Audit Events,” on page 1024 


19.1 Enabling Auditing 


You can configure Access Manager to send audit events to Analytics Server. If you require to use any 
other server for auditing except Analytics Server, then you can configure Access Manager to send 
audit events to a Sentinel server, a Syslog server, or Novell Audit Server (on upgraded systems only). 


In addition to the selectable events, device-generated alerts are automatically sent to the audit server. 
These Management Communication Channel events have an ID of 002e0605. All Access Manager 
events begin with 002e. 


For information about audit event IDs and field data, see Section 30.17, “Access Manager Audit 
Events and Data,” on page 1292. 


Access Gateway also supports sending e-mail notification to system administrators. To configure this 
system in Administration Console, click Devices > Access Gateways > Edit > Alerts. 


NOTE: The eDirectory audit configuration remains unchanged even after you upgrade to the latest 
version of the Access Manager. To fetch eDirectory audit events, manually unload and re-load the 
audit modules. Perform this activity each time you start eDirectory. 


To install and enable eDirectory packages, see Installing Novell Audit Packages in the eDirectory 8.8 
SP8 Administration Guide. 


Configuring Access Manager for Auditing 


By default, Access Manager is preconfigured to use syslog. If you install more than one instance of 
Administration Console for failover, syslog server is installed with each instance. However, if you 
already use a third party syslog server, you can configure Access Manager to use your audit server. If 
you are using Analytics Server, you can configure Access Manager to use Analytics Server’s in-built 
audit server. 


Access Manager allows you to specify only one audit server. You still have failover if the audit server 
is not reachable. The failover mechanism changes based on the type of logging: 


+ For File-based: Does not require a failover mechanism. 


+ For Syslog: The events are sent to a local file. The syslog client must be configured for failover. 
For more information, see the third party syslog server documentation. 


If you have a Sentinel server or a Sentinel Log Manager server, you can configure Access Manager 
to send the events to them. 


If you have installed Analytics Server, you can configure Access Manager to send the events to 
Analytics Server. 
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This section includes the following topics: 


¢ Section 19.1.1, “Specifying the Logging Server and Console Events,” on page 1017 
¢ Section 19.1.2, “Configuring Syslog for Auditing,” on page 1019 
¢ Section 19.1.3, “Configuring Devices for Auditing,” on page 1020 


19.1.1 Specifying the Logging Server and Console Events 


The Secure Logging Server manages the flow of information to and from the auditing system. It 
receives incoming events and requests, logs information to the data store, monitors designated 
events, and provides filtering and notification services. It can also be configured to automatically reset 
critical system attributes according to a specified policy. 

1 To specify the logging server, click Auditing. 

2 Fill in the following fields: 

Audit Messages Using: Select any one of the following: 
+ Platform Agent (Discontinued): (Only on an Upgraded Access Manager) 


+ Log File (Not Recommended For Production): (Only on a fresh installation of Access 
Manager) 


The audit events are sent to a local log file. The file locations are: 
On Windows: 


¢ Identity Server and ESP: "C:\Program 
Files(x86)\Novell\Syslog\audit_common. log" 


+ Access Gateway: "C:\Program Files\Novell\Syslog\audit_ag.1log" 
On Linux: 
¢ Identity Server and ESP: /var/opt/novell/syslog/audit_common. log 
+ Access Gateway: /var/opt/novell/syslog/audit_ag.log 
+ Syslog: From the list, select a syslog server. The available options are: 
¢ Send to Sentinel: The audit event are sent in CSV format. 
¢ Send to Third party: The audit events are sent in JSON format. 


NOTE: If Administration Console is configured as a remote Audit server for syslog, 
then, the audit logs are sent to the following location: /var/log/NAM_Audits.1og. 


Ħ Send to Analytics Server: The audit event are sent in CSV format. 


Server Listening Address: Specify the IP address or DNS name of the audit logging server you 
want to use. By default, the system uses the primary Administration Console IP address. If you 
want to use a different Secure Logging Server, specify that server here. For example, if you 
select syslog, specify the syslog server details here. 


NOTE 


+ If you have enabled Analytics Server cluster configuration, the virtual IP address is auto- 
populated. For information about cluster configuration, see Post-Installation Cluster 
Configuration for Analytics Server . 


+ Access Manager supports auditing through syslog only on TCP. 


+ On Windows, if syslog is selected for auditing, the Server Listening Address field is 
disabled. To specify the server details, manually install and configure the local syslog client. 
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Server Public NAT Address: If your auditing server is in the private network, enter Public NAT 
IP Address of the auditing server using which devices can reach the auditing server. 


To use a Sentinel server or a Sentinel Log Manager, specify the IP address or DNS name of the 
Sentinel. 


+ For more information about Sentinel, see Sentinel 7.3. 
¢ For more information about Sentinel Log Manager, see Sentinel Log Manager 1.0. 


Port: Specify the port that the Platform Agents or syslog uses to connect to the Secure Logging 
Server. 


+ For Platform Agent: The default secure logging server port is 1289. 

¢ For Syslog: 
+ For Sentinel server, the default port is 1468. 
¢ For third party syslog servers, specify the configured port of that server. 
¢ For Analytics Server, specify 1468. 


NOTE: If you select Sentinel server for auditing through syslog, then you must use the latest 
Access Manager Collector for Sentinel. 


Stop Service on Audit Server Failure: Enable this option to stop the Apache services when 
the audit server is offline or not reachable and audit events could not be cached. 

Under Management Console Audit Events, specify the system-wide events you want to audit: 
Select All: Selects all of the audit events. 

Health Changes: Generated whenever the health of a server changes. 

Server Imports: Generated whenever a server is imported into Administration Console. 
Server Deletes: Generated whenever a server is deleted from Administration Console. 
Server Statistics: Generated periodically whenever statistics are generated for server. 
Configuration Changes: Generated whenever you change a server configuration. 

Click OK. 


If you did not change the address or port of the Secure Logging Server, this completes the 
process. It might take up to fifteen minutes for the events you selected to start appearing in the 
audit files. 


(Conditional) If you want to change the IP for Analytics server, you must change the IP of the 
primary Analytics Server. For information about changing the primary IP address, refer 
Section 4.5.4, “Managing Details of a Cluster,” on page 352. 


(Conditional) If Administration Console is the only Access Manager component installed on the 
machine and you have changed the address or port of the Secure Logging Server, complete the 
following steps: 


For security reasons, the Novell Audit Configuration file cannot be modified using Administration 
Console when it is the only Access Manager component on the machine. It can only be edited by 
a system administrator. 


For Administration Console, if syslog is selected for auditing, manually perform the following 
configuration: (Applicable only on SLES 11 SP4) 


1. Inthe /etc/sysconfig/syslog file, change the SYSLOG_DAEMON value to rsyslog. This will 
change the default syslog daemon to rsyslog, if it is currently not the default syslog daemon. 


2. Edit the /etc/rsyslog.d/nam.conf file and specify the following parameters: 
Sample nam.conf file: 


19.1.2 


19.1.2.1 


$InputTCPServerRun 1290 

$template ForwardFormat, "<%PRI%>%TIMESTAMP: : :date-rfc3164% %HOSTNAME% 
%sySlogtag:1:32%%msg: ::sp-if-no-1st-sp%%msg%\n" 

localO.* @@172.16.50.50:1468; ForwardFormat 


This will enable local rsyslog agent to communicate to local TCP port 1290 and forward the 
audit message to remote server 172.16.50.50 communicating with port 1468. 
3. Restart the local syslog daemon. 


4. Select the audit message format and audit server type by editing the file /etc/ 
Auditlogging.cfg. 
Sample Auditlogging.cfg file: 
LOGDEST=syslog 
FORMAT=JSON 


SERVERIP=127.0.0.1 
SERVERPORT=1290 


5. Restart Administration Console. 
6. Open a terminal window, then enter the command for your platform: 
Linux: /etc/init.d/novell-ac restart OR rcnovell-ac restart 
Windows: 
+ For Administration Console: net stop Tomcat7 net start Tomcat7 
+ For Identity Server and Access Gateway: net stop Tomcat net start Tomcat 
To restart syslog, run the following commands: 
¢ For SLES: rcrsyslog restart 
+ For RHEL: systemctl restart rsyslog.service 
7. Restart each device imported into Administration Console. 


The devices (Identity Server and Access Gateway) do not start reporting events until they 
have been restarted. 


Configuring Syslog for Auditing 


Access Manager supports syslog for auditing. You can use Analytics Server, or a Sentinel server to 
send audit events. To configure syslog, see “Specifying the Logging Server and Console Events” on 
page 1017. 


On Linux, if you select syslog for auditing, then the syslog server configurations are automatically 
pushed to Identity Server and Access Gateway. 


On Windows, you need to manually install the preferred syslog service and configure it to 
communicate to the local TCP port 1290. To configure the syslog agent to communicate with the 
remote syslog server, you need to manually configure the installed syslog agent on each device. 


Prerequisites 


To view the prerequisites, see Upgrading Access Manager. 
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19.1.2.2 


19.1.2.3 


19.1.3 


Limitations 


The following are the limitations of syslog: 


+ On Identity Server and ESP, the events are cached to a local file during a local audit failure. The 
file locations: 
On Windows: 


+ Identity Server and ESP: C:\Program Files(x86)\Novell\Syslog\audit_common. log 


On Linux: 
¢ Identity Server and ESP: /var/opt/novell/syslog/audit_common. log 
+ The log forwarding of cached logs in not supported for Identity Server and ESP events. 


+ The failover mechanism communication does not work in Access Gateway. 


IMPORTANT: By default, syslog agents are configured without SSL communication with the remote 
audit server. You need to manually configure SSL between local syslog agent and remote syslog 
audit server. 


Caching Audit Events 


By default, the local syslog agents do not cache or queue the audit events when the remote syslog 
audit server is not reachable. This results in the loss of audit events. It is recommended to enable 
cashing for audit events in the local syslog agent. 


On Linux, you can make use of the rsylsog’s queuing feature for caching the audit events. 
A sample configuration for caching the audit event is as follows: 


$WorkDirectory /rsyslog/work 
$ActionQueueType LinkedList 
$ActionQueueFileName example_fwd 
g$ActionResumeRetryCount -1 
$ActionQueueSaveOnShutdown on 


You need to create the /rsyslog/work directory manually. Add this sample configuration into the / 
etc/rsyslog.d/nam.conf file. 


NOTE: You need to manually make the changes on each component — Administration Console, 
Identity Server and Access Gateway. 


For more information about syslog configuration, see Syslog Configuration Whitepaper. 


Configuring Devices for Auditing 


Each device defines the events that can be enabled for auditing. For information about enabling 
these events, see the following: 


¢ Section 19.3, “Enabling Access Gateway Audit Events,” on page 1024 
¢ Section 19.2, “Enabling Identity Server Audit Events,” on page 1021 


For a listing of all the audit events logged by Access Manager, see Section 30.17, “Access Manager 
Audit Events and Data,” on page 1292. 
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19.2 Enabling Identity Server Audit Events 


The following steps assume that you have already set up auditing on your network. For more 
information, see “Configuring Access Manager for Auditing” on page 1016. 

1 Click Devices > Identity Server > Servers > Edit > Auditing and Logging. 

2 In the Audit Logging section, select Enabled. 

3 Select the events for notification. 


Select All: Select this option for all events. Otherwise, select one or more of the following: 


Event 


Login Provided 


Login Provided Failure 


Login Consumed 


Login Consumed Failure 


Logout Provided 


Logout Local 


Federation Request Sent 


Federation Request Handled 


Defederation Request Sent 


Defederation Request Handled 


Register Name Request Handled 


Attribute Query Request Handled 


Web Service Query Handled 


Web Service Modify Handled 


User Account Provisioned 


User Account Provisioned Failure 


Description 


Generated when an identity provider sends authentication to a 
service provider. Role assignment audit events are included in 
authentication audit events for Identity Server. 


Generated when an identity provider attempts to send 
authentication to a service provider but fails. 


Generated when a user is authenticated either locally or by an 
external identity provider. Role assignment audit events are 
included in authentication audit events for Identity Server. 


Generated when Identity Server initiates authentication, but the 
process fails. 


Generated when an identity provider sends a logout request to a 
service provider that it has authenticated. 


Generated when Identity Server receives a logout command 
from the user. 


Generated when a service provider attempts to federate with an 
identity provider. 


Generated by Identity Server when processing a request for 
federation. 


Generated by the identity provider when a request for 
defederation is sent to another provider. 


Generated when Identity Server processes a request for 
defederation. 


Generated when Identity Server processes a request for 
changing a name identifier. 


Generated by Identity Server when processing an attribute 
request from a service provider. 


Generated when a Web service query request is sent to an 
identity provider. 


Generated when Web service modify request is sent to an 
identity provider. 


Generated by Identity Server when functioning as an identity 
consumer and when an account has been provisioned. 


Generated by Identity Server when functioning as an identity 
consumer and when account provisioning has failed. 
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Event 
LDAP Connection Lost 
LDAP Connection Reestablished 


Server Started 


Server Stopped 


Server Refreshed 


Intruder Lockout Detected 


Component Log Severe Messages 
Component Log Warning Messages 


Brokering Across Groups Denied 


Brokering Rule Evaluated to Deny 


Brokering Handled 


WebService Request Authenticated 


WebService Request Authentication 
Failed 


Token Was Issued To WebService 


Token Issue To WebService Failed 


Token Was Validated To A WebService 


Token Validation To WebService Failed 


Token Renewed 

Token Renew Failed 

Risk-Based Authentication Succeeded 
Risk-Based Authentication Failed 


Risk-Based Authentication Action 
Invoked 


Risk-based Pre-authentication 
Succeeded 


Risk-based Pre-authentication Failed 


Description 


Generated when the LDAP connection is lost. 
Generated when the LDAP connection is reestablished. 


Generated when the server gets a start command from the 
server communications module. 


Generated when the server gets a stop command from the 
server communications module. 


Generated when the server gets a refresh command from the 
server communications module. 


Generated when an attempt to log in as a particular user with an 
invalid password has occurred more times than is allowed by the 
directory. 


Logged for all component messages with level of Severe. 
Logged for all component messages with level of Warning. 


Brokering authentication request denied to a target service 
provider. The brokering group consists of either the Identity 
Provider or target Service Provider, but both does not belong to 
the same group. 


Brokering authentication request denied to a target service 
provider due to broker policy evaluation resulted in denying. 


The total number of brokering authentication requests handled 
by Identity Server when it started. 


Generated when a user is authenticated for requesting a token 
for a Web service. 


Generated when a user’s authentication fails for requesting a 
token for a Web service. 


Generated when a token is issued for accessing a Web service. 


Generated when a request to issue a token for accessing a Web 
service fails. 


Generated when a token is validated for a Web service. 


Generated when a token validation for accessing a web service 
fails. 


Generated when a token is renewed for a Web service. 
Generated when renewing a token for a Web service fails. 
Generated when the rule execution succeeds. 

Generated when the rule execution fails. 


Generated when the rule execution succeeds and the user is 
requested to perform additional authentication. 


Generated when pre-authentication rule execution succeeds. 


Generated when pre-authentication rule execution fails. 


Event 


Risk-based Pre-authentication Action 
Invoked 


Risk-based IP List Load From 
Datasource Failed 


Risk-based Device Fingerprint Rule 
Created 


Risk-based Device Fingerprint Rule 
Match Failed 


OAuth & OpenID Token Issued 


OAuth & OpenID Token Issue Failed 


Description 


Generated when the pre-authentication rule execution succeeds 
and the user is requested to perform additional authentication. 


Generated when fetching the IP address list from the datasource 
fails. 


Generated when a new fingerprint rule is created for a user 
device. 


Generated when a device fingerprint does not match with the 
stored device fingerprint. 


Generated when an OAuth Authorization code, OAuth token, ID 
token, or Refresh token is issued. 


Generated when OAuth Authorization code issue, OAuth token 


issue, ID Token issue, or Refresh token issue failed. 


OAuth Consent Provided Generated when OAuth consent is provided to a client 


application. 


Generated when OAuth consent is revoked from a client 
application. 


OAuth Consent Revoked 


OAuth Client Applications Generated when a client is registered, updated, deleted, or 


client registration fails. 


OAuth & OpenID Token Validation 
Success 


Generated when an OAuth and OpenID token is validated 
successfully. 


OAuth & OpenID Token Validation 
Failed 


Generated when an OAuth and OpenID token validation fails. 


Session Assurance Device Fingerprint 
Match Failed 


Generated when device fingerprint match fails for an Identity 
Server session. 


4 Click Apply > OK. 
5 Click Servers > Update Servers. 


NOTE: Identity Server logs the IP address of client machine, from where authentication requests 
originate, into audit events. If the client machine is behind a proxy, then proxy IP address will be 
logged. If you need to skip the proxy IP address and log the actual client machine IP address, 
configure the RemotelpValve in the Tomcat configuration file (server .xm1) on all Identity Servers. 


The server.xml file can be found at /opt/novell/nam/idp/conf/server . xm1 (for linux) and // 
Program File x(86)/Novell/Tomcat/conf/server.xml (for Windows). 


For more information about configuring RemotelpValve, see Remote IP Valve (http:// 
tomcat.apache.org/tomcat-8.0-doc/config/valve.html#Remote_IP_Valve). 


To configure audit events to capture the source IP address of the X-forwarded-header, add the 
following details after the Engine element in the server. xml file: 


<Engine defaultHost="localhost" name="Catalina"> 

<Valve className="o0rg.apache.catalina.valves.RemoteIpValve" 
internalProxies="IP addresses" /> 

Substitute IP addresses with the IP address of the proxy and load balancer. 
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Restart Tomcat by using rcnovell-idp restart. 


19.3 Enabling Access Gateway Audit Events 


The following steps assume that you have already set up auditing on your network. For more 
information, see “Configuring Access Manager for Auditing” on page 1016. 


1024 Auditing 


1 Click Devices > Access Gateways > Edit > Auditing. 
2 Based on the event category, select the events for notification. 


Select All: Select this option for all events. Otherwise, select one or more of the following: 


Events 


Event 


Access Denied 


Identity Injection Failed 


System Started 
System Shutdown 
Form Fill Failed 
Application Accessed 
URL Not Found 


IP Access Attempted 


Oauth & OpenID Token Validation 
Failed 


Session Created/Destroyed 


Session Assurance Device 
Fingerprint Match Failed 


High Volume Events 


Event 


Access Allowed 


Identity Injection Success 


Form Fill Success 


URL Accessed 


Description 


Generated when a requested action is denied because the 
requester has insufficient access rights to a URL. 


Generated when the Identity Injection policy injects with the value 
field empty. 


Generated when Access Gateway is started. 

Generated when Access Gateway is stopped. 

Generated when a Form Fill policy fails to successfully fill in a form. 
Generated when a user accesses applications. 

Generated when a requested URL cannot be found. 


Generated when a user attempts to access a URL with an IP 
address instead of the published DNS name configured in Access 
Gateway. 


Generated when an OAuth and OpenID token validation fails. 


Generated when an Access Gateway session starts or ends. This 
event provides the data for Access Gateway Active Users graph of 
Information Dashboard. 


Generated when a fingerprint match fails during an Access 
Gateway session. 


Description 


Generated when a requested action is allowed because the 
requester has the correct access rights to a URL. 


Generated when the Identity Injection policy successfully injects 
data into the HTTP header. 


Generated when a Form Fill policy successfully fills in a form. 


Generated when a user accesses a URL. 


IMPORTANT: Enabling High Volume Events may generate high volume of audit events on a 
system with heavy load. This may degrade the performance of Access Gateway. 


Audit Filters 
Select the following filters to exclude them from the audit events: 


Filter Description 

CSS Excludes CSS files as part of response from the audit events. 
JavaScripts Excludes JavaScripts from the audit events. 

Images Excludes images from the audit events. Specify the image format. 


For example: JPEG, PNG 
URLs Matching Regular Expression Excludes URLs matching the configured regular expression. 


It helps in filtering out specified URL paths from the ones audited as 
part of the URL Accessed audit event. These filtered out URL paths 
will not be displayed in the Audit Server. This is helpful where 
auditing every URL is not required and may increase the load on 
the Audit Server. 


The regular expression is standard perl based regular expressions. 
For more information about “Regular Expressions”, see http:// 
perldoc.perl.org/perlre.html. 


Each URL (path?querystring) is matched against this expression. If 
the match is successful, the URL will not be audited for URL 
access. 


For example: 


+ To exclude the health check messages from auditing: /nesp/ 
app/heartbeat 


+ To exclude the auditing of URL under the path /images/: / 
images/* 


3 To save your modifications, click OK twice. 
4 On Access Gateways page, click Update. 
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20.1 


Reporting 


¢ Section 20.1, “Overview,” on page 1027 

¢ Section 20.2, “Using Reporting with Sentinel,” on page 1028 

¢ Section 20.3, “Using Reporting with Analytics Server,” on page 1029 
¢ Section 20.4, “Enabling Reporting,” on page 1030 

¢ Section 20.5, “Generating Reports in Sentinel,” on page 1031 


Overview 


Access Manager uses Analytics Server or Sentinel Solution Pack to generate reports. Analytics 
Server is easier to install and not only generates reports but also generates a dashboard to view 
visual analytics. But, if you do not want to use Analytics Server, then you must have a Sentinel setup 
with the solution pack, which consists of predefined report definitions. Access Manager requires 
Sentinel or Sentinel Log Manager to use this feature. You can use these reports to analyze users’ 
accesses to applications protected by Access Manager, in auditing, and for compliance purposes. 


NOTE: Platform Agent and Novell Audit are no longer supported. Access Manager 4.3 installation no 
longer installs Platform Agent and Novell Audit for auditing. If you upgrade from an older version of 
Access Manager to 4.3, Platform Agent is still available. It is recommended to use Syslog for auditing. 


You can generate and download the following canned reports: 


+ NetIQ Access Manager Application Access Summary 

+ NetIQ Access Manager Application Specific User Access 

+ NetIQ Access Manager Federation Summary 

+ NetIQ Access Manager User Application Access Summary 

+ NetIQ Access Manager User Login Contract Summary 

+ NetIQ Access Manager User Login Failure Report 

+ NetIQ Access Manager Application Specific Risk based Authentication Report 
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The following diagram illustrates the Access Manager reporting architecture when integrated with 
Sentinel: 


a Solution Pack 
Identity Provider 


Events 


o EH 


Administration Console 


Sentinel Server P 
PDF Reports 


Events (Sentinel User Interface) 


Access Gateway WGA 
e ccess 


Manager Collector 


+ When an event occurs in Identity Server or Access Gateway, Platform Agent (PA) or Syslog 
sends it to Sentinel. 


¢ In Sentinel, Access Manager Collector parses these events and saves event data in the Sentinel 
database. 


+ The Access Manager Reporting Solution Pack provides predefined report templates. You can 
use this template against event data to generate PDF reports. 


+ You can access a report through the Sentinel user interface by using a web browser. 


20.2 Using Reporting with Sentinel 


This section covers the details on using reporting feature through the Solution Pack. 


¢ Section 20.2.1, “Prerequisites,” on page 1028 
¢ Section 20.2.2, “Deploying Access Manager Reporting Solution Pack,” on page 1029 


20.2.1 Prerequisites 


The following list includes prerequisites for using Access Manager Reporting Solution Pack: 
¢ Install Sentinel 7.1 (or later) or Sentinel Log Manager 1.2.2 (or later). 
For information about how to install Sentinel, see the Sentinel Installation Guide. 


For information about how to install Sentinel Log Manager, see the Sentinel Log Manager 
Installation Guide. 
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+ Deploy Access Manager Reporting Solution Pack. See Section 20.2.2, “Deploying Access 
Manager Reporting Solution Pack,” on page 1029. 


+ Deploy Access Manager Collector Pack for Sentinel. The collector pack is available at the 
Sentinel Plug-ins site. 


20.2.2 Deploying Access Manager Reporting Solution Pack 


To use the predefined report templates of the solution pack, you must deploy Access Manager 
Reporting Solution Pack in the Sentinel system. The solution pack is available at the Sentinel Plug- 
ins site. 


For information about how to deploy Access Manager Reporting Solution Pack, see the Access 
Manager Reporting Solution Pack Guide. 


After deploying the solution pack, perform the following steps to verify that Access Manager reports 
are added: 

1. Log in to Sentinel or Sentinel Log Manager. 

2. Click Reports and Searches. 

3. Verify that NetIQ Access Manager reports are listed. 


20.3 Using Reporting with Analytics Server 


This section covers details on using reporting feature through analytics Server. 


¢ Section 20.3.1, “Prerequisites,” on page 1029 
¢ Section 20.3.2, “Viewing Reports,” on page 1029 


20.3.1 Prerequisites 


¢ Install Analytics Server. 
For information about installing Analytics Server, see Installing Analytics Server in the NetIQ 
Access Manager 4.3 Installation and Upgrade Guide. 

¢ Configure Analytics Server by using Administration Console. 


For information about configuring Analytics Server, refer Section 4.5, “Analytics Server 
Configuration,” on page 349. 


For information about configuring Analytics Server cluster, refer Section 4.5.3, “Analytics Server 
Cluster Configuration,” on page 352. 


¢ Enable auditing. 
For information about enabling auditing, refer Section 19.1, “Enabling Auditing,” on page 1016. 


20.3.2 Viewing Reports 


To view the Access Manager reports perform the following in Administration Console: 


1 Click Devices > Analytics Servers > Reports. 
2 On the left pane, click Reports and Searches tab. 
3 Click NetIQ Access Manager. 
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20.4 Enabling Reporting 


To enable the reporting feature, perform the following steps: 
1 Enable Events: The following table provides the list of events that are required for specific 
reports. You can enable the required events. 


For more information about how to enable Access Gateway events, see Section 19.3, “Enabling 
Access Gateway Audit Events,” on page 1024. 


For more information about how to enable Identity Server events, see Section 19.2, “Enabling 
Identity Server Audit Events,” on page 1021. 


The following table lists Access Manager reports and associated events: 


Name of Report Description Event Component 
NetIQ Access Manager Application Summary of applications Application Access 
Access Summary accessed at a specified time Access Gateway 
NetIQ Access Manager User Users who accessed a Application Access 
Application Access Summary particular application at a Access Gateway 


specified time 


NetIQ Access Manager Application Number of applications Application Access 
Specific User Access accessed by a specific user Access Gateway 
at a specified time 


NetIQ Access Manager Federation Users who accessed a Federation Identity 
Summary federated service ata Request Sent Server 
specified time and Federation 
Request 
Handled 
NetIQ Access Manager User Login Number of user login based Login Consumed Identity 
Contract Summary on authentication contracts at Server 


a specified time 


NetIQ Access Manager User Login Number of failed login Login Consumed Identity 
Failure Report attempts and their reasons Failure Server 
NetIQ Access Manager Application Number of risk-based Risk-based Identity 
Specific Risk based Authentication authentication attempts and Authentication Server 
Report the action taken for each Succeeded 
attempt at a specified time for 
a specific application. Risk-based 
Authentication 
Failed 
Risk-based 
Authentication 


Action Invoked 


2 Configure the IP Address of Audit Server: Perform the following steps: 
2a Log in to Administration Console. 
2b Click Auditing. 
2c Specify the following details: 


Server Listening Address: (ForSentinel Server or Sentinel Log Manager in Access 
Manager) Specify the Sentinel server IP address. 
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(For Analytics Server) Specify the primary address of Analytics Server. If you are using a 
cluster setup, then specify the virtual IP address that you defined during installation 
procedure. 


Port: Specify the default port as 1468. 
2d Click Apply > OK. 


20.5 Generating Reports in Sentinel 


In Sentinel, after deploying Access Manager Solution Pack and Collector, you can generate reports. 
For information about how to generate, schedule, search, export, manage, and delete a report, see 

Reporting in the Sentinel User Guide or Reporting in the Sentinel Log Manager Administration Guide 
depending on the tool you are using. 


NOTE: For sample reports, see Section D, “Access Manager Reports Samples,” on page 1471. 


Reporting 1031 


1032 Reporting 


21.1 


Logging 


Logging is the main tool you use for debugging the Access Manager configuration. You can enable 
and configure how the system performs logging. All administrative and end-user actions and events 
are logged to a central event log. This allows easy access to this information for security and 
operational purposes. Additionally, the log system provides the ability to monitor ongoing activities 
such as identity provider authentication activity, up-time of the system, and so on. File logging is not 
enabled by default. 


Each Access Manager device has configuration options for logging: 


Identity Server: Logging is turned off and must be enabled. When you enable Identity Server 
logging, you also enable logging for the Embedded Service Providers that are configured to use 
Identity Server for authentication. For configuration information, see Section 21.3.1, “Configuring 
Logging for Identity Server,” on page 1038. 


Embedded Service Providers: Each Access Manager device has an Embedded Service Provider 
that communicates with Identity Server. Its log level is controlled by configuring Identity Server 


logging. 


Access Gateway Appliance: A log notice level of logging is enabled by default. You can change the 
level from the command line interface. For information, see Section 21.4.1, “Managing Access 
Gateway Logs,” on page 1048. 


Access Gateway Service: The Gateway Service logs contain the messages sent between the 
Gateway Service and the Embedded Service Provider and between the Gateway Service and the 
Web server. This type of logging is turned off and must be enabled. For information, see 

Section 21.4.1, “Managing Access Gateway Logs,” on page 1048. 


This sections discusses the following topics: 


¢ Section 21.1, “Understanding the Types of Logging,” on page 1033 

¢ Section 21.2, “Understanding the Log Format,” on page 1035 

¢ Section 21.3, “Identity Server Logging,” on page 1038 

¢ Section 21.4, “Access Gateway Logging,” on page 1047 

¢ Section 21.5, “Downloading Log Files,” on page 1058 

¢ Section 21.6, “Turning on Logging for Policy Evaluation,” on page 1062 


Understanding the Types of Logging 


Access Manager supports two types of logging: 


¢ Section 21.1.1, “Component Logging for Troubleshooting Configuration or Network Problems,” 
on page 1034 


¢ Section 21.1.2, “HTTP Transaction Logging for Proxy Services,” on page 1034 
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21.1.1 Component Logging for Troubleshooting Configuration or 
Network Problems 


Each Access Manager component maintains log files that contain entries documenting the operation 
of the component. Component file logging records the processing and interactions between the 
Access Manager components that occur while satisfying user and administrative requests and during 
general system processing. By enabling the correct levels of logging for the various Access Manager 
components, an administrator can monitor how the Access Manager processes user and 
administrative requests. Transaction flows have been defined to help the administrator identify the 
processing steps that occur during the execution of specific types of user or administrative requests. 
All component file logs include tags and values that allow the administrator to identify and correlate 
which component file log entries pertain to a given transaction and user. 


Component file logs are not primarily intended for debugging the software itself, although they can be 
used to detect software that is not behaving properly. Rather, the intent of component file logging is to 
document the operational processing of the Access Manager components so that system 
administrators and support personnel can identify and isolate problems caused by configuration 
errors, invalid user data, or network problems such as broken connections. However, component file 
logging is typically the first step in identifying software bugs. 


Component file logging is more verbose than audit logging. It increases processing load, and ona 
day-to-day basis, it should be enabled only to log error conditions and system warnings. If a specific 
problem occurs, component file logging can be set to info or config to gather the information needed 
to isolate and repair the detected problem. When the problem is resolved, component file logging 
should be reconfigured to log only error conditions and system warnings. 


Log files can be configured to include entries for the following events: 


¢ Initialization and shutdown 
¢ Configuration 


+ Events processed by the component, such as authentication, role assignment, resource access, 
and policy evaluation 


+ Error conditions 


See Section 21.3.1, “Configuring Logging for Identity Server,” on page 1038. 


21.1.2 HTTP Transaction Logging for Proxy Services 


Access Gateway allows you to log HTTP transactions. You can log what happens with an HTTP 
request and response during certain times: 


+ Between the browser and Access Gateway 
+ Between Access Gateway and the back-end Web server 


You select fields from the HTTP header of a request and these fields are logged. You can then use 
these logged transactions to bill customers for Web services or to troubleshoot whether a request is 
refused because the browser did not send the required information or because Access Gateway did 
not’ send the Web server the required information. 


This type of logging conforms to the W3C specification for proxy server logging in the common and 
extended log formats. This type of logging provides no information about the exchanges between 
Access Gateway and Identity Server. If you need to discover whether Access Gateway is obtaining 
the correct information from Identity Server for an Identity Injection or Form Fill policy, you need to 
turn on component logging. See Section 21.3.1, “Configuring Logging for Identity Server,” on 

page 1038. 
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For HTTP transaction logging, see Section 21.4.4, “Configuring Logging for a Proxy Service,” on 
page 1050. 


21.2 Understanding the Log Format 


Access Manager does not have a fixed format for file log entries. However, to facilitate the use of non- 
interactive stream-oriented editors such as sgrep, sed, awk, and grep and to improve log entry 
readability, the log entries in the catalina. out files use some standard elements. These entries use 
the beginning and ending log entry tags and the log entry correlation tags. The data portion of log 
entries is the most flexible part. A log entry has the following fields: 


<amLogEntry> [\n] 

time-date-stamp 

[log preamble]: 

AM#event -code: 

AMDEVICE#device-id: 

AMAUTHID#auth-id: 

AMEVENTID#event - id: 

[..additional correlating information] [\n] 

[supplementary log entry data and text ... \n] 
</amLogEntry> [\n] 


Most log entries do not use the optional line breaks ([\n]). Notice that the time-date-stamp, the log 
preamble, the correlation tags, and optional additional correlating information are on the same line so 
that stream-oriented editors that use only one line (such as grep) can be used to locate log entries 
that are related. The following entry is an example entry that is logged when a user has initiated a 
login sequence. 


<amLogEntry> 2009-06-08T21:06:25Z INFO NIDS Application: AM#500105014: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#BB11C254B7521B5E836D8703826287 AF: 
Attempting to authenticate user cn=jwilson, o=novell with provided credentials. </ 
amLogEntry> 


Table 21-1 Fields in a Log Entry 


Field Description 

Beginning, ending tags The <amLogEntry> and </amLogEntry> tags mark the beginning and the end 
of a log entry. These tags allow stream-oriented editors to extract log entries for 
processing. 

Time-date-stamp tag The date and time is specified in the W3C profile format of ISO 8061. It has the 


following fields: year-month-day-T-hour-minutes-seconds-time zone. The Z 
value for the time zone indicates that the time is specified in UTC. 


Log preamble This information is optional, and usually consists of a string indicating the 
logging level (such as warning, informational, or debug) and a string identifying 
the type of module making the entry. 


In the example log entry, the preamble has a log level and a module identifier 
and contains the following strings: INFO NIDS Application: 
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Field 


Correlation tags 


Additional correlation 
information 


Supplementary information 


Description 


The correlation tags uniquely identify the event, the device that produced the 
event, and the user who requested the action. The example log entry contains 
the following correlation tags: 


AM#500105014: AMDEVICEID#9921459858EAAC29: 
AMAUTHID#BB11C254B7521B5E836D8703826287AF: 


For more information, see “Understanding the Correlation Tags in the Log 
Files” on page 1036. 


This information is optional and contains correlation tags and data unique to a 
specific type of trace. For example, a policy evaluation trace created by the 
Embedded Service Provider contains the following additional tags: 


+ NXPESI|ID#value 
+ POLICYID#value 


The example log entry does not contain any additional correlation information. 
For a log entry that does, see “Identity Injection Traces” on page 1283. 


This information is optional and contains information that is specific to the log 
entry. It can be as simple as an informational string, such as the string in the 
example log entry: 


Attempting to authenticate user cn=jwilson, o=novell with 
provided credentials. 


The supplementary information can have a very specific format. For an 
example and explanation of the policy trace information, see “Understanding 
Policy Evaluation Traces” on page 1273. 


21.2.1 Understanding the Correlation Tags in the Log Files 


There is no fixed field format for log file entries. However, because most requests handled by Access 
Manager are processed by multiple Access Manager components, there is a mechanism that 
facilitates the correlation of log entries for a single Access Manager request in the various component 
log files. A correlation tag has the following general format: 


<tag name>#<tag value>: 


The <tag name> is a fixed value, defined in the Format column of Table 21-2. It is always terminated 
by the # character. The <tag value> immediately follows the # character and is always terminated by 
the : character. The <tag value> is not a fixed value, but a uniquely assigned value to identify an 
event, a user, or a transaction. Table 21-2 lists the defined correlation tags: 


Table 21-2 Correlation Tags 


Type Format 


Description 


Event code AM#<Event -Code>: This tag is included in all log entries that record an event and in 
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all events that are presented to the user as an informational or 
error page. 


21.2.2 


Type Format Description 


User ID AMAUTHID#<ID>: An authentication identifier that Identity Server or the 
Embedded Service Provider (ESP) assigns to each 
authenticated user. This tag is included in all entries that 
pertain to a request made by an authenticated user. 


Currently Identity Server and ESP assign different 
authentication IDs. When correlating the flow of events 
between Identity Server and the ESP for an authentication 
sequence, you can use the event code of the authentication 
events and find the artifact that the ESP and Identity Server 
exchange. 


In the catalina. out file of Identity Server, search for 
AM#500105018 events. This is the event that sends the artifact 
to the ESP. Search for a corresponding artifact in Access 
Gateway log. Events AM#500105020 and AM#500105021 
contain the artifact value. 


Device ID AMDEVICE#<ID> An identifier that uniquely identifies the Access Manager 
device that is generating the log entry. 


You can view the identifier that is assigned to each device on 
the General Logging page in Administration Console (click 
Auditing > General Logging). The ID begins with a prefix that 
identifies the type of device such as idp for Identity Server, ag 
for an Access Gateway, and idp-esp for ESP of the device. The 
prefix is followed by a 16-digit hexadecimal number. 


In log entries, the idp prefix is not recorded. For example, the 
General Logging page displays idp-AA257DA77ED48DB0 for 
the ID of Identity Server, but in the catalina. out file, the 
value is AMDEVICE#AA257DA77ED48DB0. 


Transaction ID AMEVENTID#<ID>: An identifier assigned to each Access Manager or system 
administration transaction. Access Manager transactions are 
actions such as authenticating a user, processing a request for 
access to a resource, and federating an identity. 


If a user requests access to multiple resources, each request 
is given a separate transaction ID. When Access Gateway 
evaluates a policy for a protected resource page and the page 
contains links, the policy is evaluated for each link, and each of 
these evaluations generates a new transaction ID. 


System administration transactions are actions such as 
importing a device, deleting a device, stopping or starting a 
device, and configuring or modifying the configuration of a 
device. 


Sample Scenario 


The following scenario illustrates how these tags can be used. A user receives an error page 
indicating that the user has been refused access to a protected resource. The error page contains an 
event code. The user contacts the system administrator and reports the event code contained in the 
message. The code displayed to the user includes both an event number and an identifier indicating 
the device detecting the error, for example, 300101023 -92E1B234. The 300101023 value is the event 
number and 92E1B234 is the device identifier. The device identifier is the number assigned to the 
Access Manager device reporting the error. You can make a textual search of log entries using the 
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21.3.1 


21.3.1.1 


tags and values AM#300101023: and AMDEVICEID#92E1B234: to locate candidate log entries of the 
target Access Manager transaction flow. When the desired log entry is found, the AMEVENTID# tag 
and value and the AMAUTHID# tag (assuming the user has been authenticated) from the log entry can 
be used to locate all other log entries pertaining to the user in the context of the transaction. 
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¢ Section 21.3.1, “Configuring Logging for Identity Server,” on page 1038 
¢ Section 21.3.2, “Configuring Session-Based Logging,” on page 1040 
¢ Section 21.3.3, “Capturing Client Side Stack Traces,” on page 1046 


Configuring Logging for Identity Server 


If you change or enable logging, you must update Identity Server configuration and restart the 
Embedded Service Providers to apply the changes. When you disable logging, you must also restart 
the Embedded Service Providers. 


This section discusses the following topics: 


¢ Section 21.3.1.1, “Enabling Component Logging,” on page 1038 
¢ Section 21.3.1.2, “Managing Log File Size,” on page 1040 


Enabling Component Logging 


File logging records the actions that have occurred. For example, you can configure Identity Server 
logging to list every request made to the server. With log file analysis tools, you can get a good idea of 
where visitors are coming from, how often they return, and how they navigate through a site. The 
content logged to file logging can be controlled by specifying logger levels and by enabling statistics 


logging. 
1 Click Devices > Identity Servers > Edit > Auditing and Logging. 
2 File Logging: The following options are available for component logging: 


¢ Enabled: Enables file logging for this server and its associated Embedded Service 
Providers. 


+ Echo To Console: Copies Identity Server XML log file to /var/opt/novell/nam/logs/ 
idp/tomcat/catalina.out (Linux), or to /Program Files (x86)/Novell/Tomcat/logs/ 
stdout . log (Windows Server 2012). You can download the file from Auditing > General 
Logging. 

For the Embedded Service Providers, the log file location depends upon the device: 


+ For an Access Gateway Appliance or a Linux Access Gateway Service, this sends the 
messages to the catalina. out file of the device. 


+ For a Windows Access Gateway Service, this sends messages to the stdout . log file 
of the device. 


+ Log File Path: Specifies the path that the system uses to save Identity Server XML log file. 
The default path is /var/opt/novell/nam/logs/idp/nidplogs. 


If you change this path, you must ensure that the user associated with configuring the 
identity or service provider has administrative rights to the Tomcat application directory in 
the new path. 
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If you have a mixed platform environment (for example, Identity Server is installed on 
Windows and Access Gateway is on Linux), do not specify a path. In a mixed platform 
environment, you must use the default path. 


+ Maximum Log Files: Specifies the maximum number of Identity Server XML log files to 
leave on the machine. After this value is reached, the system deletes log files, beginning 
with the oldest file. You can specify Unlimited, or values of 1 through 200. 10 is the default 
value. 


+ File Wrap: Specifies the frequency (hour, day week, month) for the system to use when 
closing an XML log file and creating a new one. The system saves each file based on the 
time you specify and attaches the date and/or time to the filename. 


+ GZip Wrapped Log Files: Uses the GZip compression utility to compress logged files. The 
log files that are associated with the GZip option and the Maximum Log Files value are 
stored in the directory you specify in the Log File Path field. 


3 Component File Logger Levels: Specify the logging sensitivity for the following protocols: 
Application: Logs system-wide events, except events that belong to a specific subsystem. 
Liberty: Logs events specific to the Liberty IDFF protocol and profiles. 

SAML 1: Logs events specific to the SAML1 protocol and profiles. 
SAML 2: Logs events specific to the SAML2 protocol and profiles. 
WS Trust: Logs events specific to the WS-Trust protocol. 

WS Federation: Logs events specific to the WS Federation protocol. 


OAuth and OpenID Connect: Logs events specific to the OAuth and OpenID Connect 
protocols. 


Web Service Provider: (Liberty) Logs events specific to fulfilling Web service requests from 
other Web service consumers. 


Web Service Consumer: (Liberty) Logs all events specific to requesting Web services from a 
Web service provider. 


Use the drop-down menu to categorize logging sensitivity. Higher logging levels also include the 
lower levels in the log. 


¢ Off: Turns off component file logging for the selected item. 
¢ Severe: Logs serious failures that can cause system processing to not proceed. 


+ Warning: Logs potential failures, but the impact on execution is minimal. Warnings indicate 
that you should be aware that this event is happening and might want to make a 
configuration change to avoid it. 


¢ Info: Logs informational events. No execution or data impact occurred. 


+ Verbose: Logs static configuration information. The system logs any configuration errors 
under one of the primary three levels: Severe, Warning, and Info. 


+ Debug: Includes all of the preceding levels. 


4 Statistics Logging: (Optional) Enable this option if you want the system to periodically send the 
system statistics, in string format, to the current file logger. Statistical data (such as counts, 
levels, and so on) are included in the file log. 


4a In the Statistics Logging section, select Enabled. 
4b In the Log Interval field, specify the time interval in seconds that statistics are logged. 


5 Audit Logging: For information about configuring Audit Logging, see Section 19.2, “Enabling 
Identity Server Audit Events,” on page 1021. 


6 Click OK. 
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7 Update Identity Server. 
8 Restart Embedded Service Providers on the devices. 


When you disable component logging, you need to update Identity Servers and restart 
Embedded Service Providers. 


Managing Log File Size 
On Linux, the logrotate daemon manages the log files located in the following directories: 


/opt/novell/nam/logs 
/opt/volera/roma/logs/ 


On Windows, you need to manually monitor the size of the log files. On Linux, the logrotate daemon 
manages the log files located in the following directories: 


/opt/novell/nam/idp/logs 
/opt/volera/roma/logs/ 


The logrotate daemon has been configured to scan the files in these directories once a day. It rolls 
them over when they have reached their maximum size and deletes the oldest version when the 
maximum number of copies have been created. 


If you want to modify this behavior, see the following files in the /etc/logrotate.d directory: 


novell-tomcat7 
novell-devman 


For information about the parameters in these files, see the documentation for the logrotate daemon. 


Configuring Session-Based Logging 


The session-based logging feature allows the administrator to enable file logging for an individual 
user. In production environments, this has the following value: 


+ Debug logging can be turned on for an individual user rather than all users. The potential size of 
logged data usually prohibits an administrator from turning on debug logging for all users. 


+ All logged messages for this user are directed to a single file. Administrators do not need to sort 
through the various log files to follow the activity of the user. 


¢ Isolating the problem and finding the cause is limited to the user who is experiencing the 
problem. 


¢ Enabling session-based logging does not require a configuration change to Identity Server, and 
thus does not require updating Identity Server. 
The following user scenario explains how this feature could be used in a production environment 


1. Auser notices a problem and calls the help desk. 


2. The help desk operator questions the users and concludes that the problem is caused by either 
a Access Manager Identity Server or an Embedded Service Provider. 


3. The operator has been granted the rights to create logging tickets, and uses the User Portal to 
create a logging ticket for the user. 


4. The operator sends the logging ticket password and the URL to access the logging ticket class to 
the user. 


5. The user clicks the URL and enters the logging ticket password. 
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This marks the current session as “active for logging” and adds a small icon to the top right of the 
page, which makes the session logging feature visible to the user. 


6. Using the same browser window, the user duplicates the problem behavior. 


7. The operator can then access the data that was logged just for this user and analyze the cause 
of the behavior. 


To enable session-based logging, the following tasks need to be completed: 


¢ Section 21.3.2.1, “Creating the Administrator Class, Method, and Contract,” on page 1041 


¢ Section 21.3.2.2, “Creating the Logging Session Class, Method, and Contract,” on page 1042 


¢ Section 21.3.2.3, “Enabling Basic Logging,” on page 1043 


¢ Section 21.3.2.4, “Responding to an Incident,” on page 1043 


Creating the Administrator Class, Method, and Contract 


The IDP Administrator class, method, and contract control who has the rights to create a logging 
ticket. You need to know the DNs of the operators who are going to be responding to the users who 
are experiencing problems. 


1 Click Devices > Identity Servers > Edit > Local. 


2 To create the class: 


2a Click Classes. 


2b 


2c 


Click New, then specify the following values: 

Display name: IDP Administrator 

Java class: Other 

Java class path: com.novell.nidp.authentication.local.IDPAdministratorClass 
Click Next, then click Finish. 


3 To create the method: 
3a Click Methods. 


3b 


3c 


3d 


Click New, then specify the following values: 
Display name: IDP Administrator Method 
Class: IDP Administrator 

Identifies user: Deselect this option. 


User Stores: Select the user stores that contain your operators, then move them to the list 
of User Stores. 


In the Properties section, click New, then specify the following to create an IDP 
Administrator: 


Property Name: Administrator1 


The Property Name must begin with Administrator; append a value to this so that each 
property has a unique value. 


Property Value: cn=jdoe, o=users 


The Property Value must be the DN of an operator in the user stores you selected in 
Step 3b. Use LDAP typed comma notation for the DN. 


Repeat Step 3c for each IDP Administrator you require. 
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You can return to this method to add or remove IDP Administrators, when responsibilities 
change. 


3e Click Finish. 
4 To create the contract: 

4a Click Contracts. 

4b Click New, then specify the following values: 
Display name: IDP Administrator Contract 
URI: urn:novell:nidp:admin: contract 
Methods: Move the IDP Administrator Method to the Methods list. 
Leave all other fields with their default values. 

4c Click Next, then specify the following values for the authentication card: 
ID: IDPAdmin 
Text: IDP Administrator 


Image: Select an image from the list, such as the IDP Administrator image that was created 
for this type of contract. 


Show Card: Deselect this option. 
4d Click Finish. 
5 Continue with “Creating the Logging Session Class, Method, and Contract” on page 1042. 


21.3.2.2 Creating the Logging Session Class, Method, and Contract 


1 Click Devices > Identity Servers > Edit > Local. 
2 To create the class: 
2a Click Classes > New, then specify the following values: 
Display name: Logging Session 
Java class: Other 
Java class path: com.novell.nidp.authentication.local.LogTicketClass 
2b Click Next > Finish. 
3 To create the method: 
3a Click Methods. 
3b Click New, then specify the following values: 
Display name: Logging Session Method 
Class: Logging Session 
Identifies user: Deselect this option. 


User Stores: Select the user stores that contain the users that potentially can experience 
problems, then move them to the list of User Stores. 


3c Click Finish. 
4 To create the contract: 
4a Click Contracts. 
4b Click New, then specify the following values: 
Display name: Logging Session Contract 


URI: urn: novell:nidp:loggingsession: contract 
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Methods: Move the Logging Session Method to the Methods list. 
Leave all other fields with their default values. 

4c Click Next, then specify the following values for the authentication card: 
ID: LogSession 
Text: Logging Session 


Image: Select an image from the list, for example the Session Logging image that was 
created for this type of contract. 


Show Card: Deselect this option. 
4d Click Finish. 
5 Click OK, then update Identity Server. 
6 Continue with “Enabling Basic Logging” on page 1043. 


Enabling Basic Logging 


For session-based logging to function, logging on Identity Server must be enabled. However, you do 
not need to select what is logged. The Logging Ticket enables the appropriate components and levels 
when an incident occurs. 
1 Click Devices > Identity Servers > Edit. 
2 Click Auditing and Logging, then specify the following: 
File Logging: Enable this option. 
Echo To Console: Enable this option. 


No other options need to be enabled. The Component File Logger Levels can be left in their 
default state of off. 


3 Click OK, then update Identity Server. 


This completes the configuration. You now need to wait for a user to report a problem. For 
information about using this feature to respond to a problem, see “Responding to an Incident” on 
page 1043. 


Responding to an Incident 


The following sections explain how to use the feature when a user reports a problem: 
¢ “Creating a Logging Ticket” on page 1043 
¢ “Enabling a Logging Session” on page 1045 
e “Viewing the Log File” on page 1046 
Creating a Logging Ticket 
These steps are performed by an Identity Server administrator when a user reports a problem: 


1 Log in to Identity Server by using the credentials of an administrator. 
If the base URL of Identity Server is https://idp.amlab.net:8443/nidp, enter the following URL: 


https://idp.amlab.net:8443/nidp/app 


2 (Optional) If you do not see the Administrator tab (legacy UI) or the Logging Ticket... menu item 
(latest Ul), then you must execute the app/login?id=IDPAdmin URL to enable the Logging 
Ticked functionality. 
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The id specified in the URL must match the ID you specified for Identity Server Administrator 
Contract. See Step 4c of “Creating the Administrator Class, Method, and Contract” on 
page 1041. 


3 To create a ticket for the user, click the Administrator tab. 


3a Click New. 
3b Specify the following: 
Ticket: Specify a name for ticket. 
You must share this name with the user who reported the problem. 
Ticket Good For: Select a time limit for the ticket, from one minute through one year. 
When selecting a time limit, consider the following: 


+ When a ticket expires, logging is automatically stopped. If you know that user is 
experiencing a problem that prevents the user from logging out, you might want to 
create a ticket with a short time limit. 


+ Ifthe user does not log out (just closes the browser window or the problem closes it), 
the session remains in the list of logged sessions. After 10 minutes of inactivity, the 
session is closed and the lock on the log file is cleared. As long as the log file is locked, 
no other application can read the file. 


Ticket Log Level: Select the level of information to log, from severe-only messages to 
debug. 


Log to Console: Select to log the messages to the user’s file and to the console. 


+ If you have set up logging for session-based logging (see “Enabling Basic Logging” on 
page 1043), then this allows you see the messages in the catalina. out or 
stdout.. log file. 


+ If you have enabled Component File Logger Levels, selecting this option can create 
duplicate entries in the catalina. out or stdout. log file. 


3c Click Create. 


4 Create a URL that uses the following format: 


https://<base_URL>/nidp/app/1login?id=<LogSession> 
Replace <base_URL> with the base URL of your Identity Server, including the port. Ensure that 
the port agrees with the HTTP scheme (either http or https). 


Replace <LogSession> with the ID you specified for the authentication card when defining the 
Logging Session contract. 


IMPORTANT: The id is the ID of the authentication card of the Logging Session contract (see 
Step 4c of “Creating the Logging Session Class, Method, and Contract” on page 1042). It is not 
the name of the ticket you just created. 


If the base URL of Identity Server is https://idp.amlab.net:8443/nidp and the ID for the 
authentication card is LogSession, create the following URL: 


https://idp.amlab.net :8443/nidp/app/login?id=LogSession 


5 Send the URL of the LogSession card and the name of the ticket to the user. 


Enabling a Logging Session 


These steps are performed by the user. The URL needs to be sent to the user, with the ID and ticket 
values that were specified in “Creating a Logging Ticket” on page 1043. 
1 Open a browser and enter the log session URL sent by the help desk. 


If the URL does not display a page that prompts for the ticket name, check the value of the id 
string. The id must be set to the ID of the authentication card of the Logging Session contract. 


Instead of sending the user a URL, you can enable the Show Card option for the Logging 
Session card. When you do this, all users can see it. You need to decide if this is acceptable. 


When the Show Card option is enabled, the login page looks similar to the following: 


Authentication 


Ticket: | 
User Identifier: | 


The User Identifier may be anything that identifies the user: 
any name, number, or id. It will be used to create the log file 
name. This will make associating log files with users easier. 


_ login | 


2 When prompted, enter the following: 
Ticket: Specify the ticket name that the help desk sent. 


User Identifier: Specify a value that the help desk associates with you as a user. The identifier 
must be less than 33 characters and contain only alphanumeric characters. 


3 Click Login. 
This login creates the logging session. 
4 Enter your name and password, then click Login. 
This login authenticates you to Identity Server. 
5 In the same browser window, enter the URL of the resource that is causing the problem. 
6 Perform any other actions necessary to create the problem behavior. 
7 Log out and send your user identifier to the help desk. 
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Viewing the Log File 


These steps are performed by someone who has had Access Manager training and understands the 
significance of the messages in the log files. This can be an IDP Administrator or a specialist. 


1 On Identity Server, change to the Tomcat log directory. 


Linux: /var/opt/novell/nam/logs/idp/nidplogs 


Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- 
INF\logs 


Open the file that begins with the user identifier to which a session ID is appended. 


If the user does not log out (just closes the browser window or the problem closes it), the session 
remains in the list of logged sessions. After 10 minutes of inactivity, the session is closed and the 
lock on the logging file is cleared. As long as the file is locked, no other application can read the 
file. 


When a ticket expires, logging is stopped automatically. If you know that user is experiencing a 
problem that prevents the user from logging out, you might want to create a ticket with a short 
time limit. 

(Conditional) If the user was experiencing a problem with an Embedded Service Provider, 
change to the Tomcat log directory on the device: 

Linux: /opt/novell/nam/idp/webapps/nesp/WEB- INF/logs 


Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\nesp\WEB- 
INF\logs 


Open the file with the same user identifier and session ID. 


5 After solving the problem, delete the file from each Identity Server in the cluster and each Access 


Gateway in the cluster. 


21.3.3 Capturing Client Side Stack Traces 


Perform the following steps to save the client side exceptions into the catalina.out file through a 
JSP page: 
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1 On Linux /opt/novell/nam/idp/webapps/nidp and on Windows C:\Program Files 


(x86) \Novell\Tomcat \webapps\nidp, create the following files: 


testerror.jsp: 


<%@ page language="java" contentType="text/html; charset=ISO-8859-1" 
pageEncoding="ISO-8859-1"%> 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
"http: //www.w3.org/TR/htm14/loose.dtd"> 
<html> 
<head> 
<meta http-equiv="Content-Type" 
content="text/html; charset=IS0O-8859-1"> 
<title>TestError.JSP</title> 
</head> 
<% 
String a = null; 
out.println(" test " + a.toString()); 
%> 
</html> 


error.jsp: 


<%@ page language="java" isErrorPage="true" import="java.io.*" 
contentType="text/html; charset=ISO-8859-1" 
pageEncoding="utf -8"%> 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http:// 
www.w3.org/TR/htm14/loose.dtd"> 
<html> 
<head> 
<meta http-equiv="Content-Type" content="text/html; 
charset=utf-8"> 
<title>Default Error Page</title> 
</head> 
<body> 
Message: 
<%=exception.getMessage( )%> 
StackTrace: 
<% 
StringWriter stringwriter = new StringWriter(); 
Printwriter printWriter = new PrintWriter(stringWriter); 
exception.printStackTrace(printWriter); 
out.println(stringWriter); 
System.out.println(stringWriter); 
printwriter.close(); 
stringwriter.close(); 
%> 
</body> 
</html> 


2 On Linux /opt/novell/nam/idp/webapps/nidp/WEB- INF/web. xml file, and on Windows 
C:\Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB-INF\web. xml file, add the 
following: 


<error-page> 
<exception-type>java. lang. Throwable</exception-type> 
<location>/error.jsp</location> 
</error-page> 
If the element error-page is already available, add exception-type and update location. 


3 In idp_url:port/nidp/testerror.jsp, the stack trace is displayed on the browser and is also 
stored in the catalina. out log file. 


4 To prevent the stack trace from being displayed on the browser, remove the 
out.printin(stringWriter ) string from the error .jsp file and change isErrorPage to false 
Now, the stack trace is not displayed on the browser but is still stored in the catalina. out log 
file. 


21.4 Access Gateway Logging 


+ Section 21.4.1, “Managing Access Gateway Logs,” on page 1048 

¢ Section 21.4.2, “Configuring Logging of HTTP Headers,” on page 1049 

¢ Section 21.4.3, “Configuring Logging of SOAP Messages,” on page 1049 
¢ Section 21.4.4, “Configuring Logging for a Proxy Service,” on page 1050 
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21.4.1 Managing Access Gateway Logs 


In Access Gateway, you can configure logging by using Advanced Options. 


¢ Section 21.4.1.1, “Configuring the Log Level,” on page 1048 
¢ Section 21.4.1.2, “Configuring the Log File,” on page 1048 


21.4.1.1 Configuring the Log Level 
1 Click Devices > Access Gateways > Edit > Advanced Options. 
2 Add the following line with appropriate log level: 
LogLevel <loglevel> 


Replace /oglevel option with emerg, alert, crit, error, warn, notice, info or debug. The 
default log level is warn. 


Option Description 

emerg Sends only messages that render the system unusable, if they are not 
resolved. 

alert Sends only messages that require immediate action. 

crit Sends only messages about critical situations 

error Sends warning messages about recoverable errors. 

warn Sends warning messages. 

Notice Sends information about the status of a service to the service 


configuration logs. 


Info Sends informational messages such as requests sent to Web servers 
and the results of authentication requests. 


Debug Sends debug messages 


3 Click OK. 
4 Click Access Gateways, then click Update > OK. 


On Linux the error_log file is available at /var/opt/novell/nam/logs/mag/apache2/ whereas 
on Windows, this file is available at \ProgramFiles\Novell\Apache\logs. 


21.4.1.2 Configuring the Log File 


1 Click Devices > Access Gateways > Edit > Advanced Options. 
2 Add the following line: 
ErrorLog <path to the file where logs should be recorded> 
3 Click OK. 
4 Click Access Gateways > Update > OK. 
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21.4.2 Configuring Logging of HTTP Headers 


¢ Section 21.4.2.1, “Configuring Logging Headers in Request from Client to Proxy,” on page 1049 


¢ Section 21.4.2.2, “Configuring Logging Headers in Response from Proxy to Client,” on 
page 1049 


21.4.2.1 Configuring Logging Headers in Request from Client to Proxy 


To configure logging headers in requests from client to proxy, proxy to Web server and response from 
Web server to proxy, follow the below steps: 
1 Click Devices > Access Gateways > Edit > Advanced Options 
2 Add the following line: 
DumpHeaders <on|off> 


Setting the DumpHeaders to on ensures that the proxy logs headers to the /var/opt/novell/ 
nam/logs/mag/apache2/error_log file for linux and 
\ProgramFiles\Novell\Apache\logs\error .1log for Windows. 


NOTE: (Optional) For Access Gateway Appliance, add the line DumpHeadersFacility local6 
in addition to the DumpHeaders on option in Advanced Options. The headers will be logged in / 
var/opt/novell/nam/logs/mag/apache2/httpheaders. 


If you have configured the ErrorLog option, the logs are stored in the specified file. 
3 Click OK. 
4 Click Access Gateways > Update > OK. 


21.4.2.2 Configuring Logging Headers in Response from Proxy to Client 


1 Click Devices > Access Gateways > Edit > Advanced Options. 
2 Add the following line: 
DumpResponseHeaders <on|off> 


Setting the DumpHeaders to on ensures that the proxy logs headers to the /var/opt/novell/ 
nam/logs/mag/apache2/error_1log file for linux and 
\ProgramFiles\Novell\Apache\logs\error .1log for Windows. 


If you have configured the ErrorLog option, the logs are stored in the specified file. 
3 Click OK. 
4 Click Access Gateways > Update > OK. 


21.4.3 Configuring Logging of SOAP Messages 


To configure logging of SOAP messages in the communication between proxy and ESP, perform the 
following steps: 


1 Click Devices > Access Gateways > Edit > Advanced Options. 
2 Add the following line: 


DumpSoapMessages <on | off> 
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21.4.4 


21.4.4.1 


Setting the DumpSoapMessages to on ensures that the proxy logs SOAP messages to the / 
var/opt/novell/nam/logs/mag/apache2/error_log file for linux and 
\ProgramFiles\Novell\Apache\logs\error.1log for Windows. 


NOTE: (Optional) For Access Gateway Appliance, add the line DumpSoapMessagesFacility 
local5 in addition to the DumpSoapMessages on option in Advanced Options. The soap 
messages will be logged in /var/opt/novell/nam/1logs/mag/apache2/soapmessages. 


If you have configured the ErrorLog option, the logs are stored in the specified file. 
3 Click OK. 
4 Click Access Gateways > Update > OK. 


Configuring Logging for a Proxy Service 


Logging HTTP transactions has associated costs. Access Gateway is capable of handling thousands 
of transactions per second. If transaction volume is high and each log entry consumes a few hundred 
bytes, Access Gateway can fill up the available disk space in a matter of minutes. HTTP logging also 
increases system overhead, which causes some degradation in performance. By default, the logging 
of HTTP transactions is turned off. Before enabling logging, you need to determine what needs to be 
logged and then plan a logging strategy. For more information about custom log formats, see Apache 
Log Configuration Module. 


¢ Section 21.4.4.1, “Determining Logging Requirements,” on page 1050 

¢ Section 21.4.4.2, “Calculating Rollover Requirements,” on page 1051 

¢ Section 21.4.4.3, “Enabling Logging,” on page 1053 

¢ Section 21.4.4.4, “Configuring Common Log Options,” on page 1054 

¢ Section 21.4.4.5, “Configuring Extended Log Options,” on page 1054 

¢ Section 21.4.4.6, “Configuring the Size of the Log Partition,” on page 1057 


Determining Logging Requirements 


Because logging requirements and transaction volume vary widely, NetIQ cannot make 
recommendations regarding a specific logging strategy. The following tasks guide you through the 
process of creating a strategy that fits your business needs. 


1 Identify the reasons for tracking transactions such as customer billing, statistical analysis, or 
growth planning. 


2 Determine which resources need logging. 


You enable logging at the proxy service level. If you have a proxy service protecting resources 
whose transactions do not need to be logged, reconfigure your proxy services so that the proxy 
service you configure for logging contains only the resources for which you want to log 
transactions. 


3 Determine what information you need in each log entry. 


The common configuration for a log entry contains minimal information: the date, time, and client 
IP address for each entry. If you need more information, you can select the extended log 
configuration. Do not select all available fields, but carefully select what you really need. For 
example, you can include cookie information, but cookie information can consume a large 
amount of space and might not include any critical information you need. 
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21.4.4.2 


You should log only the essential data because a few bytes can add up quickly when Access 
Gateway is tracking thousands of hits every second. For information about what is available in 
an extended log profile, see “Configuring Extended Log Options” on page 1054. 


Design a rollover strategy. 


A log must be closed before it can be downloaded to another server for analysis or deleted. You 
specify either by time or size when Access Gateway closes a log file and creates a new one. For 
each proxy service that you enable for logging, you need to reserve enough space for at least 
two files: one for logging and one for rollover. To calculate the best procedure, see “Calculating 
Rollover Requirements” on page 1051. 


Design a log deletion strategy 


Access Gateway has a limited amount of disk space allocated for logging, and you need to 
decide how you are going to manage this space. You can limit the number of rollover files by 
number or age. To calculate the best procedure, see “Calculating Rollover Requirements” on 
page 1051. 


Calculating Rollover Requirements 


You can have Access Gateway roll over log files based on time or on size, but not both. If you already 
know which option you want to use, scan this section and then complete only the calculations 
pertinent to your choice. If you don’t know which option best matches your situation, completing the 
calculations in this section should help you decide. 


The following variables are used in the formulas: 


+ 


logpartition_size: The total disk capacity reserved for log files on Access Gateway. 


Access Gateway reserves 4 GB to share between logging and system files. The system files do 
not grow significantly, so you can assume that you have about 2 GB for logging. To increase this 
size, see “Configuring the Size of the Log Partition” on page 1057. 


logentry_size: The average log entry size. 


You can determine this by configuring a proxy service to track the required information, 
generating traffic to the proxy service, downloading the log files, determining how large each 
entry is, and calculating the average. 


request_rate: The peak rate of requests per second. 


You can estimate this rate or place your Access Gateway in service and get more accurate data 
by accessing generated statistics. See Section 22.2.1, “Monitoring Access Gateway Statistics,” 
on page 1074. 


num_services: The number of proxy services for which you plan to enable logging. 


logs_per_service: The number of log files, both active and closed, that you want Access 
Gateway to generate for each proxy service before the disk fills. 


You must plan to have at least two logs per proxy service, but you can have more. 


The following formulas can help you estimate when the system would run out of resources: 


“Calculating diskfull_time” on page 1052 
“Calculating max_roll_time” on page 1052 


“Calculating max_log_roll_size” on page 1053 
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Calculating diskfull_time 


Use the following formula to calculate how long it takes Access Gateway to fill your logging disk 
space: 


diskfull_time in seconds = logpartition_size / (request_rate * 
logentry_size * num_services) 


For example, assume the following: 


logpartition_size = 1 GB (1,073,741,824 bytes) 
request_rate = 1000 requests per second 
logentry_size = 1 KB (1,024 bytes) 
num_services = 1 


diskfull_time = (1 GB) / (1000 * 1 KB * 1) = 1048 seconds (17.47 
minutes) 


The logging disk space fills up every 17.47 minutes. 
To calculate the diskfull_time for your Access Gateway: 


1 Determine the values of the four variables listed above. 
2 Use the diskfull_time formula to calculate how often you can expect your logging disk to fill, then 
use the result in Calculating max_roll_time. 


If your diskfull_ time interval is too short to be practical for your rollover schedule, the easiest option is 
to reduce the log entry size by configuring the proxy services to log less information per transaction. 


Calculating max_roll_time 


Use the following formula to calculate the maximum rollover time value you should specify in the Roll 
over every field 


max_roll_time = diskfull_time / logs_per_service 
For example, assume the following: 

diskfull_time = 12 hours 

logs_per_service = 2 

max_roll_time = 12 / 2 = 6 hours 


If you roll your logs over by time intervals, the maximum time should be less than six hours. 
Otherwise, scheduling the download and deletion of log files is much more complicated and the 
window in which this can be done is narrower. 


To calculate the max_roll_time for your Access Gateway: 
1 Determine how many log files you want Access Gateway to generate per service before log 
space fills. 
The minimum number is two. 


2 Use the max_roll_time formula and the diskfull_ time value obtained in “Calculating diskfull_ time’ 
on page 1052 to calculate how often you should have the cache device roll over the log files. 


3 Record the max_roll_time result on your planning sheet. 
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Calculating max_log_roll_size 


Use the following formula to calculate the maximum log file size you should specify in the Maximum 
File Size field: 


max_log_roll_size = logpartition_size / (num_services * 
logs_per_service) 


For example, assume the following: 


logpartition_size = 600 MB 

num_services = 2 

logs_per_service = 3 

max_log_roll_size = 600 MB / (2 * 3) = 100 MB 


If you roll your logs over when they reach a specific size, the file size must be no more than 100 MB. 
Otherwise, the system runs out of disk space before you have three complete log files and scheduling 
the download and deletion of log files is much more complex. 


To calculate the max_log_roll_size for your Access Gateway: 


1 Determine the values of the three variables listed above. 


2 Use the max_log_roll_size formula to calculate the maximum size a log file should reach before 
the cache device rolls it over. 


Enabling Logging 


Do not enable logging until you have designed a logging strategy. See “Determining Logging 
Requirements” on page 1050. 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> Auditing and Logging. 

2 Fill in the following fields: 
Enable Logging: Select this field to enable logging. 


Log Directory: Default location for log files of proxy service is /var/log/novell/reverse/ 
<reverse_proxy_name>. 


3 In the Logging Profile List, click one of the following options: 


+ New: Click this option to create a new logging profile. Then specify a name and select 
either Common or Extended. 


¢ Default: Click Default to modify or view the settings for the Default profile. The Default 
profile uses the common log options. 


A logging profile determines the type of information that is written to the log file; it also manages 
rollover and old file options. 


4 Continue with one of the following: 
¢ “Configuring Common Log Options” on page 1054 
¢ “Configuring Extended Log Options” on page 1054 
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21.4.4.5 


Configuring Common Log Options 


Use the common log options page to control log rollover and old file options. The data included in a 
log entry is controlled by a default configuration that includes the following: 

+ Date and time of the request 

+ IP address of the client 

+ Remote host name 

+ The request line as it came from the client 

+ The HTTP status code returned to the client 

+ The number of bytes in the document transferred to the client 
Access Gateway does not allow active log files to be deleted. Only log files that have been closed can 


be deleted. The rollover options allow you to control when a file is rolled over and closed, and a new 
file is created. The old file options allow you to control when the rolled-over log files are deleted. 


To configure a default log file for a selected proxy service: 
1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> Auditing and Logging > [Name of Common Log Profile]. 
2 Select one of the following rollover options: 


Rollover When File Size Reaches: Rolls the file when it reaches the specified number of 
megabytes. 


Rollover every: Rolls the file at the specified interval. You can specify the interval in hours or 
days. 


¢ beginning: Specifies the day that the interval should begin. You can select a day of the 
week or the first of the month. 


+ at: Select the hour of the day that the interval should begin and the time zone (either the 
local time zone or GMT). 


3 Select one of the following old file options: 


Limit Number of Files to: Allows you to limit the number of old log files on the system to the 
number specified in this option. The oldest file is automatically deleted when this number is 
reached. All logging data in deleted files is lost. 


Delete Files Older Than: Allows you to configure Access Gateway to delete files when they are 
older than the time you specify. All logging data in deleted files is lost. 


Do Not Delete: Prevents the system from automatically deleting the log files. A maximum of 
65535 files can be stored for a proxy service when you select this option. 


4 Click OK. 
5 Click Access Gateways > Update > OK. 


Configuring Extended Log Options 


Use the extended log options page to control log entry content, log rollover, and old file options. A log 
entry always includes the date, time, and client IP address for each entry, but with the log data 
options, you can add other fields such as the IP address of the server and the username of the client. 


Access Gateway does not allow active log files to be deleted. Only log files that have been closed can 
be deleted. The rollover options allow you to control when a file is rolled over and closed, and a new 
file is created. The old file options allow you to control when the rolled-over log files are deleted. 
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To configure an extended log file for a selected proxy service: 


1 Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] 
> Auditing and Logging > [Name of Extended Log Profile]. 


2 Select one or more of the log data options: 


Name 


User Name 


Description 


The name of the user sending the 
request. 


Entry in Configuration 
File 


%u 


Sample Entry in the 
Log file 


"public’,”cn=admin,o=n 
ovell" 


Server IP 


The IP address of Access Gateway. 


a 


123.1.2.3 


Site Name 


The name of the reverse proxy. 


Av 


www.lagssl.com 


Method 


The HTTP method the browser 
sent to Access Gateway. 


%mM 


GET,POST 


URI 


The HTTP URL the browser sent to 
Access Gateway. 


%U 


nam/acme_ss_js7.html 


URI Stem 


The stem portion of the HTTP URL 
the browser sent to Access 
Gateway. The stem is everything in 
the URL up to the first question 
mark. If the URL has no question 
mark, the URI Stem field is the 
same as the URI field. URI Stem is 
redundant if URI is selected. 


/path/to/resource 


URI Query 


The query portion of the HTTP URL 
the browser sent to Access 
Gateway. The query is everything 
from the first question mark through 
the end of the URL. If the URL has 
no question mark, this field has no 
value. URI Query is redundant if 
URI is selected. 


%q 


?page=catalog&x=100 
&y=0 


Version 


The HTTP version specified in the 
URL the browser sent to Access 
Gateway. 


HTTP/1.1 


Status 


The HTTP status code Access 
Gateway sent to the browser. 


%S 


200, 304, 404 


Bytes Sent 


The number of bytes of HTTP 
response data Access Gateway 
sent to the browser. 


%l 


14378 


Bytes 
Received 


The number of bytes of HTTP 
request data the proxy service 
received from the browser. 


%0 


14378 


Time Taken 


The time it took Access Gateway 
resources to deal with the request 
in microseconds. 


%D 


0.062, 0.392, 2, 802.1 
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Name Description Entry in Configuration | Sample Entry in the 
File Log file 
User Agent | The User-Agent HTTP request %{user-agent}i Mozilla/5.0 (X11; Linux 
header value the browser sent to x86_64; rv:19.0) 
Access Gateway. Gecko/20100101 
Firefox/19.0 
Cookie The Cookie HTTP request header %{cookie} IPCZQX0355730a2b=0 
value the browser sent to Access 1001300a463874a93ef 
Gateway. Access Gateway does 23e89e9acc94468beb4 
not’ cache cookie information. b; ZNPCQ003- 
Cookies can consume a lot of 37323400=c2e51552 
space. If you select this option, 
make sure it contains the critical 
information that you need. 
Referer The Referer HTTP request header | %{Referer} https://www.lagssl.com/ 
value the browser sent to Access netiq/nam/ 
Gateway. acme_ss_js7.html 
Cached The value indicates whether the 0,1 
Status request was filled from cache. 
1 = filled from cache 
0 = not filled from cache 
Origin The IP address of the Web server. %{BALANCER_WORK | 125.1.2.5 
Server This assumes Access Gateway ER_IP}e 
retrieved the requested information 
directly from the Web server. 
X-Forward- | The X-Forwarded-For HTTP %{x-forward-for}i 10.0.0.1,10.0.02,10.0.0 
For request header value the browser 3,10.0.0.4 
sent to Access Gateway. Do not 
confuse this with the X-Forwarded- 
For option, which causes Access 
Gateway to generate or forward 
headers to upstream proxies or 
Web servers. 
Bytes The total bytes filled in response to | %l 184 
Filled the request. 
Content The byte ranges sent from Access %{Content-Range}o 
Range Gateway to a requesting browser. 
E Tag The tag sent from Access Gateway | %{ETag} 604888-1077- 
to a requesting browser. 466372c0 
Completio The completion status for the %X success, timeout, reset 
n Status transaction, indicating that it 
completed successfully or that it 
failed. Possible values: success, 
timeout, reset (the client terminated 
the connection), administrative 
(Access Gateway terminated the 
connection). 
Reply The size in bytes of the HTTP %L 361 
Header header associated with a response 
Size to a client. 


21.4.4.6 


Name Description Entry in Configuration | Sample Entry in the 
File Log file 
X Cache Brief status statement for cached %{Cache-Control}o no-store 
Info objects; brief reasons why an object 
was not cached. 
Range The Range header value. %{Range}o 
If Range The If Range header value, which %{If-Range} bytes 0-200/736 
indicates whether the browser 
request was a conditional range 
request. 
Content The size in bytes of the entire %O 741 
Length object delivered to a requesting 
browser. 
Request The pragma value associated with %{Pragma}o No-cache , no-store 
Pragma a browser request. 
Reply The pragma value associated with %{Pragma}i no-cache 
Pragma a server response to a requesting 
browser. 


3 Select one of the following rollover options: 


Rollover When File Size Reaches: Rolls the file when it reaches the specified number of 
megabytes. 


Rollover every: Rolls the file at the specified interval. You can specify the interval in hours or 
days. 


¢ beginning: Specifies the day that the interval should be begin. You can select a day of the 
week or the first of the month. 


¢ at: Select the hour of the day that the interval should begin and the time zone (either the 
local time zone or GMT). 


4 Select one of the following old file options: 


Limit Number of Files to: Allows you to limit the number of old log files on the system to the 
number specified in this option. The oldest file is automatically deleted when this number is 
reached. All logging data in deleted files is lost. 


Delete Files Older Than: Allows you to configure Access Gateway to delete files when they are 
older than the time you specify. All logging data in deleted files is lost. 


Do Not Delete: Prevents the system from automatically deleting the log files. A maximum of 
65535 files can be stored for a proxy service when you select this option. 


5 Click OK. 
6 Click Access Gateways > Update > OK. 


Configuring the Size of the Log Partition 


The size of the log partition should be configured as part of the installation process. Access Gateway 
logs are stored in the /root partition by default. You can create a /var partition to store the logs. The 
size of this partition depends on your requirements. For more information about creating the /var 
partition, see Creating Custom Partitions in the NetlQ Access Manager 4.3 Installation and Upgrade 
Guide. 
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21.5 Downloading Log Files 


The General Logging page displays the location of the files that Access Manager components use for 
logging system messages. There are some exceptions: 


¢ Default Auditing File: If you have configured Novell Audit to send events to the default audit file 


(on Linux, this is/var /opt/novell/naudit/logs/audit1log), this file does not appear in the list. 
(On a Windows machine that has different security restraints, the file appears in the list.) 


If you want this file to appear in this list on a Linux machine, you must make this file readable by 
the noviwww user. It is a breach of Novell Audit security for Access Manager code to change the 
permissions on this file. You must decide whether changing its permissions and displaying the 
file in this list compromises your security. 


To add this file in the list of files for Administration Console, configure the following: 
+ Use commands similar to the following to grant the novlwww user executable permissions to 
the naudit directories: 
chmod o+rx /var/opt/novell/naudit 


chmod o+rx /var/opt/novell/naudit/logs 


+ Use a command similar to the following to grant the novlwww user read access to the 
audit1log file: 


chmod otr /var/opt/novell/naudit/logs/auditlog 


Proxy Service Log Files: If you enable proxy service logging, these files are not available for 
downloading from this page because there could be potentially hundreds of these files. If this 
type of logging has been enabled, the directory where they are located is displayed. For more 
information about this type of logging, see Section 21.4.4, “Configuring Logging for a Proxy 
Service,” on page 1050. 


To view or download a log file: 


1 Click Auditing > General Logging. 


2 Select one or more log files, click Download, then open it or save it to disk. 


You can use any text editor to view the file. 


Each Access Manager component generates multiple log files. The following tables lists these files 
and the types of messages they contain: 


+ 
+ 


+ 
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Section 21.5.1, “Linux Administration Console Logs,” on page 1059 

Section 21.5.2, “Windows Server 2012 Administration Console Logs,” on page 1059 
Section 21.5.3, “Linux Identity Server Logs,” on page 1060 

Section 21.5.4, “Windows Server 2012 Identity Server Logs,” on page 1060 


Section 21.5.5, “Linux Access Gateway Appliance and Access Gateway Service Logs,” on 
page 1060 


Section 21.5.6, “Windows Access Gateway Service Logs,” on page 1061 


21.5.1 


21.5.2 


Linux Administration Console Logs 


Filename 


/var/opt/novell/nam/logs/adminconsole/ 
tomcat/catalina.out 


/var/opt/novell/nam/logs/adminconsole/volera/ 
app_sc.0.log 


/var/opt/novell/nam/logs/adminconsole/volera/ 
app_cc.0.log 


/var/opt/novell/nam/logs/adminconsole/volera/ 
platform.0.log 


Description 


Contains Tomcat errors. 


Contains events related to importing devices, device 
configuration changes, health status changes, statistics 
reporting, and communication problems. 


Contains events related to policy configuration. 


Contains XML events for configuration changes. This log file 
contains very little useful information for system 
administrators. 


Windows Server 2012 Administration Console Logs 


NOTE: Platform Agent and Novell Audit are no longer supported. A new Access Manager 4.2 
installation no longer installs Platform Agent and Novell Audit for auditing. If you upgrade from an 
older version of Access Manager to 4.2, Platform Agent is still available. It is recommended to use 


Syslog for auditing. 


Filename 


\Program Files (x86)\Novell\Tomcat\ 
logs\stderr.log 


\Program Files (x86)\Novell\Tomcat\ 
logs\stdout.log 


\Program Files (x86)\Novell\logs\ app_sc.0.log 


\Program Files (x86)\Novell\logs\ app_cc.0.log 


\Program Files (x86)\Novell\logs\ 
platform.0.log 


Description 

Contains Tomcat error messages directed to stderr. 
This file is reset whenever Tomcat is restarted. 
Contains Tomcat error messages directed to stdout. 
This file is reset whenever Tomcat is restarted. 


Contains events related to importing devices, device 
configuration changes, health status changes, statistics 
reporting, and communication problems. 


Contains events related to policy configuration. 


Contains XML events for configuration changes. This log file 
contains very little useful information for system 
administrators. 
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21.5.3 Linux Identity Server Logs 


Filename 


/var/opt/novell/nam/logs/idp/tomcat/catalina.out 


/var/opt/novell/nam/logs/jcc/jcc-0.log.0 


Description 


Logging to this file occurs only if you have selected the Echo 
to Console option from the Identity Servers > Servers > 
Edit > Auditing and Logging page. 


When component logging has been set to info for 
Applications, it contains entries tracing user authentication 
and role assignments. 


Contains the log entries for the server communications 
module related to interaction of Identity Server with 
Administration Console, such as imports, certificates, health 
checks, and configuration. 


21.5.4 Windows Server 2012 Identity Server Logs 


Filename 


\Program Files (x86)\Novell\Tomcat\ 
logs\stderr.log 


\Program Files (x86)\Novell\Tomcat\ 
logs\stdout.log 


\Program Files (x86)\Novell\devman\ jcc\logs\jcc- 
0.log.0 


Description 
Contains Tomcat error messages directed to stderr. 
This file is reset whenever Tomcat is restarted. 


Logging to this file only occurs if you have selected the 
Echo to Console option from the Identity Servers > 
Servers > Edit > Auditing and Logging page. 


When component logging has been set to info for 
Applications, it contains entries tracing user authentication 
and role assignments. 


This file is reset whenever Tomcat is restarted. 


Contains the log entries for the server communications 
module related to interaction of Identity Server with 
Administration Console, such as imports, certificates, health 
checks, and configuration. 


21.5.5 Linux Access Gateway Appliance and Access Gateway 


Service Logs 


Filename 


/var/opt/novell/nam/logs/mag/tomcat/catalina.out 
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Description 


Logging to this file only occurs if you have selected the 
Echo to Console option from the Identity Servers > 
Servers > Edit > Auditing and Logging page. 


Check this file for entries tracing the evaluation of 
authorization, identity injection, and form fill policies. 


Filename Description 


/var/log/novell/reverse/<proxy_service-name> If logging is enabled on one or more reverse proxies, this 
directory contains the log files. To enable this type of 
logging, see Section 21.1.2, “HTTP Transaction Logging 
for Proxy Services,” on page 1034. 


A directory is listed for each reverse proxy on which you 
have enabled logging. 


/var/opt/novell/nam/logs/jcc/jcc-0.log.0 Contains the log entries for the server communications 
module related to interaction of Access Gateway with 
Administration Console, such as imports, certificates, 
health checks, and configuration. 


/var/opt/novell/nam/logs/mag/apache2/error_log Contains the diagnostic information and records of any 
errors that it encounters in processing requests.To enable 
this type of logging, see Section 21.4.1, “Managing Access 
Gateway Logs,” on page 1048. 


This directory also contains the Apache generated log files 
such as the error_log file. 


/var/opt/novell/nam/logs/mag/amlogging/ Contains the messages generated for configuration, 

ags_error.log device imports, health, and statistics. It also contains 
entries for the policy evaluation processes done by the 
Gateway Service Manager module. 


/var/opt/novell/nam/logs/mag/amlogging/ Contains the verbose log entries. 
verbose_log 


21.5.6 Windows Access Gateway Service Logs 


Filename Description 
\Program Files\Novell\amlogging\logs\ Contains the messages generated for configuration, device 
ags_error.log imports, health, and statistics. It also contains entries for 


the policy evaluation processes done by the Gateway 
Service Manager module. 


\Program Files\Novell\amlogging\logs\ If you have enabled log profiles, this directory contains 
these log files. To enable this type of logging, see 
Section 21.4.1, “Managing Access Gateway Logs,” on 
page 1048. 


\Program Files\Novell\Apache\logs\ <name> If logging is enabled on one or more reverse proxies, this 
directory contains the log files. To enable this type of 
logging, see Section 21.4.4, “Configuring Logging for a 
Proxy Service,” on page 1050. 


This directory also contains the Apache generated log files 
such as the error_log file. 
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Filename Description 


\Program Files\Novell\Tomcat\logs\ stdout.log Contains the log messages generated by the Embedded 


Service Provider. Logging to this file only occurs if you have 
selected the Echo to Console option from the Identity 
Servers > Servers > Edit > Auditing and Logging page. 


Check this file for entries tracing the evaluation of 
authorization, identity injection, and form fill policies. 


This file is reset whenever Tomcat is restarted. 


21.6 Turning on Logging for Policy Evaluation 


Policy evaluation for roles occurs at Identity Server. For Authorization and Identity Injection policies, 
policy evaluation occurs on the Embedded Service Provider (ESP) where the policy is enabled. 


For the Form Fill policies, the evaluation and logging is done by ESP and the proxy service. To set the 
logging level on Access Gateway for the proxy service, see “Enabling Form Fill Logging” on 
page 1287. 


Logging for the policy evaluation done by ESP is controlled by the log settings of Identity Server 
configuration. To enable this type of logging: 


1 


Click Devices > Identity Servers > Edit > Auditing and Logging. 


If you have set up more than one Identity Server configuration, make sure you select the 
configuration to which the other Access Manager components have been assigned. 


2 Select Enabled for File Logging. 


3 Select to echo the trace messages to the console: 
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+ For the Linux Access Gateway Appliance, Linux Access Gateway Service, or Linux Identity 
Server, this sends the messages to the catalina. out file. 


+ For the Linux Access Gateway Service or Windows Identity Server, this sends the 
messages to the stdout . log file. 


(Optional) Specify a path for Identity Server log files. 


If you have a mixed platform environment (for example, Identity Server is installed on Windows 
and Access Gateway is on Linux), do not specify a path. 


For policy evaluation tracing, set the Application level to info in the Component File Logger 
Levels section. 


If you are only troubleshooting policies at this time, do not select any other options. This reduces 
the amount of information recorded in the log files. 


To see the policy SOAP messages, you need to set the Application level to config. 
Update Identity Server. 
Click Auditing > General Logging. 


+ For role evaluation traces, view Identity Server catalina. out file (Linux) or the 
stdout . log file (Windows). 


If your Identity Servers are clustered, you need to look at the file from each Identity Server. 


¢ For Authorization, Form Fill, and Identity Injection evaluation traces, view the log file of ESP 
of the device that is protecting the resource. 


¢ Linux Access Gateway Appliance or Service: This is the catalina. out file of 
Access Gateway where the protected resource is defined. If Access Gateway is part of 
a cluster, you need to look at this file from each Access Gateway in the group. 


To view the actual ESP log file that contains only ESP log messages, see the 
nidp.*.xm1 files in the /var/opt/novell/tomcat7/webapps/nesp/WEB- INF/logs 
directory (or the directory you specified in Step 4). Depending upon how you have 
configured File Wrap, the * portion of the filename contains the month, the week, the 
day, and the hour. 


+ Windows Access Gateway Service: This is the stdout . 1log file of Access Gateway 
where the protected resource is defined. If Access Gateway is part of a cluster, you 
need to look at this file from each Access Gateway in the group. 


To view the actual ESP log file that contains only ESP log messages, see the 
nidp.*.xml files in the \Program Files\Novell\tomcat \webapps\nesp\WEB- 

INF\ logs directory (or the directory you specified in Step 4). Depending upon how you 
have configured File Wrap, the * portion of the filename contains the month, the week, 
the day, and the hour. 


8 To understand what you are looking for in the log file, continue with one of the following: 


¢ Section 30.16.2, “Understanding Policy Evaluation Traces,” on page 1273 if you set 
Application level to info. 


¢ Section 30.6.9, “Policy Evaluation: Access Gateway Devices,” on page 1234 if you set 
Application level to config. 
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22.1 


22.1.1 


Monitoring Component Statistics 


The Statistics page allows you to monitor the amount of data and the type of data that Identity Server 
and Access Gateway processes. You can specify the intervals for the refresh rate and, where 
allowed, view graphic representations of the activity. 

¢ Section 22.1, “Identity Server Statistics,” on page 1065 

¢ Section 22.2, “Access Gateway Statistics,” on page 1074 

¢ Section 22.3, “Component Statistics Through REST APIs,” on page 1085 


Identity Server Statistics 


¢ Section 22.1.1, “Monitoring Identity Server Statistics,” on page 1065 
¢ Section 22.1.2, “Monitoring Identity Server Cluster Statistics,” on page 1073 


Monitoring Identity Server Statistics 


1 Click Devices > Identity Servers. 
2 In the Statistics column, click View. 
3 Click either of the following options: 


Statistics: Select this option to view the statistics as currently gathered. The page is static and 
the statistics are not updated until you click Live Statistics Monitoring. 


Live Statistics Monitoring: Select this option to view the statistics as currently gathered and to 
have them refreshed at the rate specified in the Refresh Rate field. 


4 Review the following statistics: 
+ “Application” on page 1066 
+ “Authentications” on page 1066 
+ “Incoming HTTP Requests” on page 1067 
+ “Outgoing HTTP Requests” on page 1067 
+ “Liberty” on page 1068 
¢ “SAML 1.1” on page 1068 
+ “SAML 2” on page 1069 
+ “WSF (Web Services Framework)” on page 1069 
+ “Clustering” on page 1071 
+ “LDAP” on page 1072 
+ “SP Brokering” on page 1072 
¢ “Risk-Based Authentication” on page 1073 
+ “OAuth” on page 1073 

5 Click Close to return to the Servers page. 
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NOTE: The statistics graphs of Identity Server and Access Gateway are available only in the primary 
Administration Console. The periodic stats are sent to the secondary Administration Console only 
when the primary console is not available. Hence, the statistics graphs of Identity Server and Access 
Gateway do not display any statistics values in the secondary Administration Console. 


22.1.1.1 Application 


Statistic Description 


Free Memory The percentage of free memory available to the JVM (Java Virtual Machine). Click 
Graphs to view memory usage for a specific unit of time (1 hour, 1 day, 1 week, 1 
month, 6 months, or 12 months). The Value axis displays the percentage of memory 
that is free for the selected time period. 


22.1.1.2 Authentications 


Statistic Description 


Provided Authentications The number of successful provided authentications given out to external entities 
after Identity Server was started. 


Consumed The number of successful consumed authentications after Identity Server was 
Authentications started. 


Provided Authentication The number of failed provided authentications given out to external entities after 
Failures Identity Server was started. 


Consumed The number of failed consumed authentications after Identity Server was started. 
Authentication Failures The Consumed Authentication Failures statistics counter increases by one 
whenever a method execution fails for the user. 


Historical Maximum The maximum number of logins served during an interval and displayed after 
Logins Served completion of the interval. 

Logins In Last Interval The number of active user sessions during the last interval. 

Logouts The number of explicit logouts performed by users. This does not include logouts 


where an inactive session was destroyed. 


Cached Sessions The number of currently active cached user sessions. This represents the number 
of users currently logged into the system; however, if a single person has two 
browser windows open on the same client and if that person performed two distinct 
authentications, then that person has two user sessions. 


Click Graphs to view the number of cached sessions for a specific unit of time (1 
hour, 1 day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the 
number of cached sessions. If no sessions have been cached, the value axis is not 


meaningful. 
Cached Ancestral The number of cached ancestral session IDs. An ancestral session ID is created 
Sessions during the failover process. When failover occurs, a new session is created to 


represent the previous session. The ID of the previous session is called an 
“ancestral session ID,” and it is retained for subsequent failover operations. 


Cached Subjects The number of current cached subject objects. Conceptually, the cached subjects 
are identical to the cached principals. 
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22.1.1.3 


22.1.1.4 


Statistic 


Cached Principals 


Cached Artifacts 


Description 


The number of current cached principal objects. A principal can be thought of as a 
single directory user object. Multiple users can log in using a single directory user 
object, in which case multiple cached sessions would exist sharing a single cached 
principal. 


The number of current cached artifact objects. During authentication, an artifact is 
generated that maps to an assertion. This cache holds the artifact to assertion 
mapping until the artifact resolution request is received. Under normal operations, 
artifacts are resolved within milliseconds of being placed in this cache. 


Incoming HTTP Requests 


Incoming HTTP requests are divided into three categories: active, interval, and historical. As soon as 
a request is complete, it is placed into the interval category. The interval represents the last 60 
seconds of processed requests. At the completion of the 60-second interval, all requests in the 
interval category are merged into the historical category. 


Statistic 


Total Requests 


Currently Active 
Requests 


Oldest Active Request 
(Milliseconds) 


Last Interval Maximum 
Request Duration 
(Milliseconds) 


Last Interval Mean 
Request Duration 
(Milliseconds) 


Historical Maximum 
Request Duration 
(Milliseconds) 


Historical Mean Request 


Duration (Milliseconds) 


Description 


The total number of incoming HTTP requests that have been processed after 
Identity Server was started. Click Graphs to view the number of requests for a 
specific unit of time (1 hour, 1 day, 1 week, 1 month, 6 months, or 12 months). The 
Value axis displays the number of requests for the selected time period. 


The number of currently active incoming HTTP requests. 


The age of the oldest currently active incoming HTTP request. 


The age of the longest incoming HTTP requests that was processed during the last 
60-second interval. 


The mean age of all incoming HTTP request that were processed during the last 60- 
second interval. 


The age of the longest incoming HTTP request that was processed after Identity 
Server was started. 


The mean age of all incoming HTTP requests that were processed after Identity 
Server was started. 


Outgoing HTTP Requests 


Outgoing HTTP requests are divided into three categories: active, interval, and historical. As soon as 
a request is complete, it is placed into the interval category. The interval represents the last 60 
seconds of processed requests. At the completion of the 60-second interval, all requests in the 
interval category are merged into the historical category. 
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22.1.1.5 


22.1.1.6 


Statistic 


Total Requests 


Currently Active 
Requests 


Oldest Active Request 
(Milliseconds) 


Last Interval Maximum 
Request Duration 
(Milliseconds) 


Last Interval Mean 
Request Duration 
(Milliseconds) 


Historical Maximum 
Request Duration 
(Milliseconds) 


Historical Mean Request 
Duration (Milliseconds) 


Liberty 


Statistic 


Liberty Federation 
Liberty De-Federations 


Liberty Register-Names 


SAML 1.1 


Statistic 


SAML1.1 Attribute 
Queries 


Description 


The total number of outgoing HTTP requests that have been processed after 
Identity Server was started. Click Graphs to view the number of requests for a 
specific unit of time (1 hour, 1 day, 1 week, 1 month, 6 months, or 12 months). The 
Value axis displays the number of requests for the selected time period. 


The number of currently active outgoing HTTP requests. 


The age of the oldest currently active outgoing HTTP request. 


The age of the longest outgoing HTTP request that was processed during the last 
60-second interval. 


The mean age of all outgoing HTTP requests that were processed during the last 
60-second interval. 


The age of the longest outgoing HTTP request that was processed after Identity 
Server was started. 


The mean age of all outgoing HTTP requests that were processed after Identity 
Server was started. 


Description 


The number of Liberty protocol federations performed after Identity Server was 
started. 


The number of Liberty protocol defederations performed after Identity Server was 
started. 


The number of Liberty protocol register names performed after Identity Server was 
started. 


Description 


The number of SAML 1.1 protocol attribute queries performed after Identity Server 
was started. 
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22.1.1.7 


22.1.1.8 


SAML 2 


Statistic 


SAML2 Attribute Queries 
SAML2 Federations 
SAML2 Defederations 


SAML2 Register-Names 


Description 


The number of SAML 2 protocol attribute queries performed after Identity Server 
was started. 


The number of SAML 2 protocol federations performed after Identity Server was 
started. 


The number of SAML 2 protocol defederations performed after Identity Server was 
started. 


The number of SAML 2 protocol register names performed after Identity Server was 
started. 


WSF (Web Services Framework) 


Statistic 


Personal Profile Service 
Queries 


Personal Profile Service 
Modifies 


Employee Profile Service 
Queries 


Employee Profile Service 
Modifies 


Custom Profile Service 
Queries 


Custom Profile Service 
Modifies 


Credential Profile 
Service Queries 


Credential Profile 
Service Modifies 


Authentication Profile 
Service Queries 


Authentication Profile 
Service Modifies 


LDAP Profile Service 
Queries 


LDAP Profile Service 
Modifies 


Constant Profile Service 
Queries 


Description 


The number of Liberty IDSIS Personal Profile Web Service queries performed after 
Identity Server was started. 


The number of Liberty IDSIS Personal Profile Web Service changes performed after 
Identity Server was started. 


The number of Liberty IDSIS Employee Profile Web Service queries performed after 
Identity Server was started. 


The number of Liberty IDSIS Employee Profile Web Service changes performed 
after Identity Server was started. 


The number of Novell Custom Profile Web Service queries performed after Identity 
Server was started. 


The number of Novell Custom Profile Web Service changes performed after Identity 
Server was started. 


The number of Novell Credential Profile Web Service queries performed after 
Identity Server was started. 


The number of Novell Credential Profile Web Service changes performed after 
Identity Server was started. 


The number of Novell Authentication Profile Web Service queries performed after 
Identity Server was started. 


The number of Novell Authentication Profile Web Service changes performed after 
Identity Server was started. 


The number of Novell LDAP Profile Web Service queries performed after Identity 
Server was started. 


The number of Novell LDAP Profile Web Service changes performed after Identity 
Server was started. 


The number of Novell Constant Profile Web Service queries performed after Identity 
Server was started. 
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Statistic 


Discovery Service 
Queries 


Discovery Service 
Modifies 


Redirected Interaction 


Service Requests 


Trusted Interaction 
Service Requests 


Client of Redirected 
Interaction Service 
Requests 


Client of Trusted 
Interaction Service 
Requests 


Data Location LDAP 


Data Location LDAP 
Aggregation 


Data Location User 
Profile 


Data Location User 
Profile Aggregation 


Data Location Remote 


Description 


The number of Liberty Discovery Web Service queries performed after Identity 
Server was started. 


The number of Liberty Discovery Web Service changes performed after Identity 
Server was started. 


The number of Liberty User Interaction Redirection Profile requests performed after 
Identity Server was started. 


The number of Liberty User Interaction Trusted Service Profile requests performed 
after Identity Server was started. 


The number of Liberty User Interaction Redirection Profile requests initiated as a 
client after Identity Server was started. 


The number of Liberty User Interaction Trusted Service Profile requests initiated as 
a client after Identity Server was started. 


The number of attempts to use LDAP as a data location for a query or a modify of 
any Web Service after Identity Server was started. 


The number of attempts to use LDAP as a data location for aggregation of a query 
or a modify of any Web Service after Identity Server was started. 


The number of attempts to use the User Profile object as a data location for a query 
or a modify of any Web Service after Identity Server was started. A User Profile 
object is a directory object stored in Identity Server's configuration datastore. 


The number of attempts to use the User Profile object as a data location for 
aggregation of a query or a modify of any Web Service after Identity Server was 
started. A User Profile object is a directory object stored on Identity Server's 
configuration datastore. 


The number of attempts to use the Remote location as a data location for a query or 
a modify of any Web Service after Identity Server was started. A Remote location 
includes Pushed Attributes and External Services. 


Data Location Pushed 
Attributes 


The number of attempts to use the Pushed Attributes as a remote data location for a 
query or a modify of any Web Service after Identity Server was started. 


Data Location Pushed 
Attributes Aggregation 


The number of attempts to use the Pushed Attributes as an remote data location for 
aggregation of a query or a modify of any Web Service after Identity Server was 
started. 


Data Location External 
Service 


The number of attempts to use an External Service as a remote data location for a 
query or a modify of any Web Service after Identity Server was started. An External 
Service is where the same Web Service exists on an external Service Provider and 
a call can be made to request data from the service. 
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22.1.1.9 


Clustering 


An authoritative server is the cluster member that holds the authentication information for a given 
user session. For a request associated with a given session to be processed, it must be routed 
(“proxied”) to the authoritative cluster member. If an L4 switch causes a request to go to a non- 
authoritative cluster member, that cluster member proxies the request to the authoritative cluster 
member. 


When a request is received, a cluster member uses multiple means to determine which cluster 
member is the authoritative server for the request. It looks for a parameter on the query string of the 
URL indicating the authoritative server. It looks for an HTTP cookie, indicating the authoritative 
server. If these do not exist, the cluster member examines the payload of the HTTP request to 
determine the authoritative server. Payload examinations result in immediate identification of the 
authoritative server or a user session ID or user identity ID that can be used to locate the authoritative 
server. 


If a user session ID or user identity ID is found, the ID is broadcast to all cluster members asking 
which member is the authoritative server for the given ID. The authoritative server receives the 
broadcast message, determines that it indeed holds the given session or user, and responds 
accordingly. 


The higher the number of proxied requests, the lower the performance of the entire system. 
Furthermore, the higher the number of payload examinations and ID broadcasts, the lower the 
performance of the entire system. If these numbers are high, verify the configuration of the L4 switch. 
Ensure that the session persistence option is enabled, which allows clients to be directed to the same 
Identity Server after they have established a session. 


Statistic Description 

Currently Active Proxied The number of currently active proxied HTTP requests. 

Requests 

Total Proxied Requests The total number of proxied requests that have been processed after Identity 


Server was started. A request becomes a proxied request when the request is 
sent first to a non-authoritative machine. 


Total Non-Proxied Requests The total number of non-proxied requests that have been processed after 
Identity Server was started. A request becomes a non-proxied request when 
the request is sent first to the authoritative machine. 


Authoritative Server Obtained The total number of authoritative servers identified by using the parameter from 
from URL Parameter the URL query string after Identity Server was started. 


Authoritative Server Obtained The total number of authoritative servers identified by using the HTTP cookie 
from Cookie after Identity Server was started. 


Payload Examinations The total number of attempted payload examinations to identify the 
authoritative server after Identity Server was started. 


Successful Payload The total number of successful payload examinations to identify the 

Examinations authoritative server after Identity Server was started. 

Identity ID Broadcasts The total number of attempted Identity ID Broadcasts to identify the 
authoritative server after Identity Server was started. 

Successful Identity ID The total number of successful Identity ID Broadcasts to identify the 

Broadcasts authoritative server after Identity Server was started. 

Session ID Broadcasts The total number of attempted Session ID Broadcasts to identify the 


authoritative server. 
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Statistic 


Successful Session ID 
Broadcasts 


22.1.1.10 LDAP 


Statistic 


User Store Replica 
Restarts 


Successful User Store 
Replica Restarts 


User Store Replica 
Restart Retries 


Currently Active 
Connection Waits 


Connection Waits 


Connection Waits 
Aborted Due To Timeout 


Connection Waits 
Aborted Due To Closed 
Pool 


22.1.1.11 SP Brokering 


Statistic 


Total Brokering Requests 


Total Brokering Requests 
Denied Due to Group 
Check 


Total Brokering Requests 
Denied Due to Role 
Deny 


Total Brokering Requests 
Passed 


Description 


The total number of successful Session ID Broadcasts to identify the 
authoritative server after Identity Server was started. 


Description 


The number of times that a user store replica became unavailable so that a restart 
was necessary after Identity Server was started. A user store restart is attempted 
once every minute. 


The number of times that a user store replica restart was successfully completed 
after Identity Server was started. 


The number of times that a user store replica restart failed and was put back into 
“wait mode” to try again in one minute after Identity Server was started. 


The current number of user threads waiting for an LDAP connection to become 
available. 


The number of times that a user thread was required to wait for an LDAP connection 
to become available after Identity Server was started. A wait would be required if the 
maximum number of connections allocated to the associated connection pool were 
all currently in use by other threads. 


The number of times that an LDAP connection wait terminated because of Identity 
Server timing out after Identity Server was started. This would result in an LDAP 
Service Not Available error. 


The number of times that an LDAP connection wait terminated because of a closed 
connection pool after Identity Server was started. This would normally be caused by 
an LDAP replica failing while the user thread is waiting for the connection. This 
would result in an LDAP Service Not Available error. 


Description 


The total number of brokering requests created after Identity Server was started. 
This count is a sum of all connections created to all replicas of the configuration 
datastore and all user stores. 


The total number of brokering authentication requests denied in a target service 
provider. The brokering group can either be the identity provider or target service 
provider but both does not belong to the same group. 


The total number of brokering authentication requests to a target service provider 
denied due to broker policy evaluation denying the role. 


The total number of brokering requests passed after Identity Server was started. 
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22.1.1.12 


22.1.1.13 


22.1.2 


Risk-Based Authentication 


Statistic 


Requests Allowed After 
Authentication 


Requests Denied After 
Authentication 


Requests Allowed Pre- 
Authentication 


Requests Denied Pre- 
Authentication 


Requests for Additional 
Authentication in Pre- 
Authentication 


Requests for Additional 
Authentication in Post- 
Authentication 


OAuth 


Statistic 


Access Token Issued 


Authorization Code 
Issued 


ID Token Issued 


Refresh Token Exchange 
to Access Token 


Token Verification Failure 
Requests 


Token Issue Failure 


Description 


The total number of low risk requests allowed after authentication. 


The total number of high risk requests denied after authentication. 


The total number of low risk requests allowed during pre-authentication. 


The total number of high risk requests denied during pre-authentication. 


The total number of additional authentication requests during pre-authentication. 


The total number of additional authentication requests during post-authentication. 


Description 


The total number of access tokens issued by the authorization server for different 
grant types. 


The total number of authorization codes issued by the authorization server. 


The total number of ID tokens issued by the authorization server. 


The total number of refresh tokens exchanged with the access token. 


The total number of token and code verification failure requests. 


The total number of token and code issue failures for different grant types. 


Monitoring Identity Server Cluster Statistics 


On the Cluster Statistics page, you can configure the list of statistics to show the desired statistics for 
an Identity Server cluster. See Section 22.1.1, “Monitoring Identity Server Statistics,” on page 1065 
for the complete list of statistics for each server in an Identity Server cluster. 


To configure the statistics, perform the following steps: 


1 In Administration Console Dashboard, click Devices > Identity Servers > [Name of Cluster] > 
Statistics > Configure. 


2 Select Set default statistics under "Selected Statistics" to replace the selected statistics with 
the default statistics. 
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The default statistics include Free Memory, Provided Authentications, Cached Sessions, Logins 
In Last Interval, Currently Active Requests - Incoming HTTP Requests, Currently Active 
Requests - Outgoing HTTP Requests, and Currently Active Proxied Requests. 


Select statistics from Available Statistics and move to Selected Statistics. 


4 Click OK. 


The Cluster Statistics page displays the summary of configured statistics for each individual 
member of the cluster. 


To view additional information about a specific Identity Server, click the name of Identity Server 
in the Server Name column of the summary. 


You can also view all the statistics for an individual server of the cluster. Click View in the 
Statistics column of the summary to see these additional statistics. For more information, see 
Section 22.1.1, “Monitoring Identity Server Statistics,” on page 1065. 


5 Click Close. 


22.2 Access Gateway Statistics 


22.2.1 


22.2.1.1 


¢ Section 22.2.1, “Monitoring Access Gateway Statistics,” on page 1074 
¢ Section 22.2.2, “Monitoring Access Gateway Cluster Statistics,” on page 1083 


Monitoring Access Gateway Statistics 


1 In Administration Console Dashboard, click Devices > Access Gateways > [Name of Server] > 


Statistics. 


2 Select from the following types: 


¢ “Server Activity Statistics” on page 1074 
¢ “Server Benefits Statistics” on page 1079 


¢ “Service Provider Activity Statistics” on page 1079 


3 Click Close. 


NOTE: The statistics graphs of Identity Server and Access Gateway are available in only the primary 
Administration Console. The periodic stats are sent to the secondary Administration Console only 
when the primary console is not available. Hence, the statistics graphs of Identity Server and Access 
Gateway do not display any statistics values in the secondary Administration Console. 


Server Activity Statistics 


Select whether to monitor live or static statistics: 


Statistics: Select this option to view the statistics as currently gathered. The page is static and the 
statistics are not updated until you click Live Statistics Monitoring. 


Live Statistics Monitoring: Select this option to view the statistics as currently gathered and to have 
them refreshed at the rate specified in the Refresh Rate field. 
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These general statistics are grouped into the following categories: 


¢ “Server Activity” on page 1075 


e “Connections” on page 1076 


e “Bytes” on page 1076 


+ “Requests” on page 1077 


+ “Cache Freshness” on page 1078 


Server Activity 


The Server Activity section displays general server utilization statistics. 


Statistic 


CPU Utilization 


Cache Hit 


Mounted Partitions Disk 
Space 


Mounted Partitions Disk 
Space Used 


Mounted Partitions Disk 
Space Free 


Swap Partition Disk 
Space 


Swap Partition Disk 
Space Used 


Swap Partition Disk 
Space Free 


Cache Disk Space 


Cache Disk Space 
Utilization 


Total Installed Memory 
Start Up Time 
Up Time 


Number of Objects 
Cached 


Description 


Displays the current CPU utilization rate. Use the available graph for capacity 
planning. 


Click Graphs to view the CPU usage for a specific unit of time (1 hour, 1 day, 1 
week, 1 month, 6 months, or 12 months). The Value axis displays the percentage of 
use. 


Displays the current cache hit rate. A high cache hit rate indicates that the caching 
system is off-loading significant request processing from the Web servers whose 
objects have been cached. 


Click Graphs to view the number of cache hits for a specific unit of time (1 hour, 1 
day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the number 
of hits. 


Displays the total disk space configured on mounted partitions. 


Displays the disk space in use on mounted partitions. 


Displays the disk space available on mounted partitions. 


Displays the total disk space configured for the swap partition. The Linux Gateway 
Service displays the available swap space reported by the Linux kernel (see sysinfo 
for details). 


(Linux) Displays the disk space in use on the swap partition. 


(Linux) Displays the disk space available on the swap partition. 


Displays the total disk space available for caching. 


Reserved. Not currently used. 


Displays the amount of memory that is installed on Access Gateway. 
Displays the last time Access Gateway was started. 
Displays the total time Access Gateway has been running since it was last started. 


Displays the total number of objects that have been cached since Access Gateway 
was last started. 
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Connections 


The connection statistics show the current and peak levels of usage in terms of TCP connections. 


Statistic 


Current Connections to 
Origin Server 


Current Connections to 
Browsers 


Current Total 
Connections 


Connections to Origin 
Server 


Peak Connections from 
Origin Server 


Connections to Browsers 


Peak Connections to 
Browsers 


Total Connections 
through SOCKS 


Failed Connection 
Attempts 


Bytes 


Description 


Displays the current number of connections that Access Gateway has established 
with Web servers. 


Displays the current number of connections that Access Gateway has established 
with browsers. 


Displays the current total of all connections that Access Gateway has established. 


Displays the total number of connections that Access Gateway has established with 
Web servers since it was last started. 


Click Graphs to view the number of connections for a specific unit of time (1 hour, 1 
day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the number 
of connections. 


Displays the peak number of connections that Access Gateway has established with 
Web servers. 


Displays the total number of connections that Access Gateway has established with 
browsers since it was last started. 


Click Graphs to view the number of connections for a specific unit of time (1 hour, 1 
day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the number 
of connections. 


Displays the peak number of connections that Access Gateway has established with 
browsers. 


Displays the total number of connections Access Gateway has established through 
a firewall. 


Displays the total number of failed connection attempts Access Gateway has made 
while attempting to fill its Web object cache. 


The bytes statistics show how fast information is being sent in response to the following types of 


requests: 


+ Browser requests to Access Gateway 


e Access Gateway requests to the Web servers 


Statistic 


Throughput of the Origin 
Server 


Description 


Displays the average number of bytes of data being sent each second from the 
Web servers to Access Gateway. 


Average number of bytes = total number of bytes sent from origin server to 
Access Gateway per system uptime in seconds. 


Click Graphs to view the number of bytes for a specific unit of time (1 hour, 1 day, 
1 week, 1 month, 6 months, or 12 months). The Value axis displays the number of 
bytes. 
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Statistic Description 


Throughput of the Browser Displays the average number of bytes of data being sent each second from 
Access Gateway to the browsers. 


Average number of bytes = total number of bytes sent from Access Gateway to 
browsers per system uptime in seconds. 


Click Graphs to view the number of bytes for a specific unit of time (1 hour, 1 day, 
1 week, 1 month, 6 months, or 12 months). The Value axis displays the number of 
bytes. 


Total Bytes per Second Displays the total number of bytes of data being sent each second from Access 
Gateway and from the Web servers. 


Click Graphs to view the number of bytes for a specific unit of time (1 hour, 1 day, 
1 week, 1 month, 6 months, or 12 months). The Value axis displays the number of 
bytes. 


Bytes Sent to Origin Server Displays the total number of bytes sent to the origin server after the server is 
started. 


Bytes Received from Origin Displays the total number of bytes of data sent to Access Gateway from the Web 
Server servers since Access Gateway last started. 


Bytes Sent to Browser Displays the total number of bytes of data sent to the browsers from Access 
Gateway since Access Gateway last started. 


Bytes Received from The total number of bytes received from the browser after the server is started. 
Browser 
Total Bytes Displays the total number of bytes of data sent from Access Gateway and from 


the Web servers since Access Gateway was last started. 


Requests 


The request statistics show the number of requests that are being sent from the browsers to Access 
Gateway and from Access Gateway to the Web servers. 


Statistic Description 
Current Requests to Displays the current number of requests that Access Gateway has made to the Web 
Origin Server servers. 


Click Graphs to view the number of requests for a specific unit of time (1 hour, 1 
day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the number 
of requests. 


Current Requests from Displays the current number of requests that the browsers have made to Access 
Browsers Gateway. 


Click Graphs to view the number of requests for a specific unit of time (1 hour, 1 
day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the number 
of requests. 


Total Current Requests Displays the total number of current requests that Access Gateway has received 
from the browsers and that Access Gateway has sent to the Web servers. 


Successful Requests to Displays the total number of successful requests that Access Gateway has sent to 
Origin Server the Web servers since Access Gateway last started. 
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Statistic 


Failed Requests to 
Origin Server 


Cumulative Requests to 
Origin Server 


Cumulative Requests to 
Browsers 


Total Cumulative 
Requests 


Requests per Second to 
Origin Server 


Requests per Second 
from Browsers 


Total Requests per 
Second 


Peak Requests per 
Second to Origin Server 


Peak Requests per 
Second from Browsers 


Cache Freshness 


Description 


Displays the total number of failed requests that Access Gateway has sent to the 
Web servers since Access Gateway last started. 


Displays the total number of requests that Access Gateway has sent to the Web 
servers since Access Gateway last started. 


Displays the total number of requests that the browsers have sent to Access 
Gateway since Access Gateway last started. 


Displays the total number of cumulative requests that Access Gateway has 
processed since Access Gateway last started. 


Displays the number of requests that are being sent each second from Access 
Gateway to the Web servers. 


Click Graphs to view the number of requests for a specific unit of time (1 hour, 1 
day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the number 
of requests. 


Displays the number of requests that are being sent each second from the browsers 
to Access Gateway. 


Click Graphs to view the number of requests for a specific unit of time (1 hour, 1 
day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the number 
of requests. 


Displays the total number of requests that are being sent each second from Access 
Gateway and from the browsers. 


Displays the peak number of requests that have been sent in one second from 
Access Gateway to the Web servers. 


Displays the peak number of requests that have been sent in one second from the 
browsers to Access Gateway. 


The cache freshness statistics display information about the cache refresh process. 


Statistic 


Total “Get If Modified 
Since” Request 


Total Not Modified 
Replies 


Cache Freshness 


Oldest Object in Memory 


Description 


Displays the total number of Get If Modified Since requests that Access Gateway 
has received from browsers. 


Displays the total number of 304 Not Modified replies that Access Gateway has 
received from the Web servers for updated content. 


Displays the percentage of objects in cache that are considered fresh. 


Click Graphs to view the percentage of fresh objects for a specific unit of time (1 
hour, 1 day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the 
percentage of fresh objects. 


Displays how long the oldest cache object has been cached. 
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22.2.1.3 


Server Benefits Statistics 


Select whether to monitor live or static statistics: 


Statistics: Select this option to view the statistics as currently gathered. The page is static and the 
statistics are not updated until you click Live Statistics Monitoring. 


Live Statistics Monitoring: Select this option to view the statistics as currently gathered and to have 
them refreshed at the rate specified in the Refresh Rate field. 


The Server Benefits page displays information about bandwidth and DNS caching: 


Statistic Description 


Total Bandwidth Saved Displays the amount of bandwidth saved by using data cached by Access 
Gateway rather than requesting the data from the Web servers. 


Bytes Saved per Second Displays how many bytes of data Access Gateway was able to send from 
cache rather than requesting it from the Web servers. 


Service Provider Activity Statistics 


Select whether to monitor live or static statistics: 


Statistics: Select this option to view the statistics as currently gathered. The page is static and the 
statistics are not updated until you click Live Statistics Monitoring. 


Live Statistics Monitoring: Select this option to view the statistics as currently gathered and to have 
them refreshed at the rate specified in the Refresh Rate field. 


The ESP Activity page displays information about the communication process between Access 
Gateway (ESP) and Identity Server. These statistics are grouped into the following categories: 

+ Application 

+ Authentications 

+ Incoming HTTP Requests 

¢ Outgoing HTTP Requests 

¢ Liberty 

e Clustering 

¢ SP Brokering 


Click Graphs to review historical statistics. 


Application 
Statistic Description 
Free Memory The percentage of free memory available to the JVM (Java Virtual Machine). 


Click Graphs to view the free memory for a specific unit of time (1 hour, 1 day, 1 
week, 1 month, 6 months, or 12 months). The Value axis displays the percentage of 
free memory. 
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Authentications 


Statistic 


Provided Authentications 
Consumed Authentications 
Provided Authentication 


Failures 


Consumed Authentication 
Failures 


Historical Maximum Logins 
Served 


Logins in Last Interval 


Logouts 


Cached Sessions 


Cached Ancestral Sessions 


Cached Subjects 


Cached Principals 


Cached Artifacts 
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Description 


The number, since Identity Server was started, of successful provided 
authentications given out to external entities. 


The number, since Identity Server was started, of successful consumed 
authentications. 


The number, since Identity Server was started, of failed provided 
authentications given out to external entities. 


The number, since Identity Server was started, of failed consumed 
authentications. 


NOTE: The consumed authentication failures does not show the number of 
invalid password attempt failures of the Identity Provider in the statistics page. 


The maximum number of logins served during an interval and displayed after 
completion of the interval. 


The number of active user sessions during the last interval. 


The number of explicit logouts performed by users. This does not include 
logouts where an inactive session was destroyed. 


The number of currently active cached user sessions. This represents the 
number of users currently logged into the system with the following caveat: If a 
single person has two browser windows open on the same client and if that 
person performed two distinct authentications, then that person has two user 
sessions. 


Click Graphs to view the number of cached sessions for a specific unit of time 
(1 hour, 1 day, 1 week, 1 month, 6 months, or 12 months). The Value axis 
displays the number of cached sessions. If no sessions have been cached, the 
value axis is not meaningful. 


The number of cached ancestral session IDs. An ancestral session ID is 
created during the failover process. When failover occurs, a new session is 
created to represent the previous session. The ID of the previous session is 
termed an “ancestral session ID,” and it is persisted for subsequent failover 
operations. 


The number of current cached subject objects. Conceptually, the cached 
subjects are identical to the cached principals. 


The number of current cached principal objects. A principal can be thought of 
as a single directory user object. Multiple users can log in using a single 
directory user object, in which case multiple cached sessions would exist 
sharing a single cached principal. 


The number of current cached artifact objects. During authentication, an 
artifact is generated that maps to an assertion. This cache holds the artifact to 
assertion mapping until the artifact resolution request is received. Under 
normal operations, artifacts are resolved within milliseconds of being placed in 
this cache. 


Incoming HTTP Requests 


Incoming HTTP requests are divided into three categories: active, interval, and historical. As soon as 
a request is complete, it is placed into the interval category. The interval represents the last 60 
seconds of processed requests. At the completion of the 60-second interval, all requests in the 
interval category are merged into the historical category. 


Statistic Description 


Total Requests The total number of incoming HTTP requests that have been processed since 
Identity Server was started. 


Click Graphs to view the number of requests for a specific unit of time (1 hour, 
1 day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the 
number of requests for the selected time period. 


Currently Active Requests The number of currently active incoming HTTP requests. 


Oldest Active Request The age of the oldest currently active incoming HTTP request. 
(Milliseconds) 


Last Interval Maximum The age of the longest incoming HTTP request that was processed during the 
Request Duration last 60-second interval. 
(Milliseconds) 


Last Interval Mean Request The mean age of all incoming HTTP requests that were processed during the 
Duration (Milliseconds) last 60-second interval. 


Historical Maximum Request The age of the longest incoming HTTP request that was processed since 


Duration (Milliseconds) Identity Server was started. 
Historical Mean Request The mean age of all incoming HTTP requests that were processed since 
Duration (Milliseconds) Identity Server was started. 


Outgoing HTTP Requests 


Outgoing HTTP requests are divided into three categories: active, interval, and historical. As soon as 
a request is complete, it is placed into the interval category. The interval represents the last 60 
seconds of processed requests. At the completion of the 60-second interval, all requests in the 
interval category are merged into the historical category. 


Statistic Description 


Total Requests The total number of outgoing HTTP requests that have been processed since 
Identity Server was started. 


Click Graphs to view the number of requests for a specific unit of time (1 hour, 
1 day, 1 week, 1 month, 6 months, or 12 months). The Value axis displays the 
number of requests for the selected time period. 


Currently Active Requests The number of currently active outgoing HTTP requests. 


Oldest Active Request The age of the oldest currently active outgoing HTTP request. 
(Milliseconds) 


Last Interval Maximum The age of the longest outgoing HTTP request that was processed during the 
Request Duration last 60-second interval. 
(Milliseconds) 


Last Interval Mean Request The mean age of all outgoing HTTP requests that were processed during the 
Duration (Milliseconds) last 60-second interval. 
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Statistic 


Historical Maximum Request 
Duration (Milliseconds) 


Historical Mean Request 
Duration (Milliseconds) 


Liberty 


Statistic 


Liberty Federation 
Liberty De-Federations 


Liberty Register-Names 


Clustering 


Description 


The age of the longest outgoing HTTP request that was processed, since 
Identity Server was started. 


The mean age of all outgoing HTTP requests that were processed, since 
Identity Server was started. 


Description 


The number of Liberty protocol federations performed, since Identity Server 
was started. 


The number of Liberty protocol de-federations performed, since Identity Server 
was started. 


The number of Liberty protocol register names performed, since Identity Server 
was started. 


An authoritative server is the cluster member that holds the authentication information for a given 
user session. For a request associated with a given session to be processed, it must be routed 
(“proxied”) to the authoritative cluster member. If an L4 switch causes a request to go to a non- 
authoritative cluster member, then that cluster member proxies that request to the authoritative 


cluster member. 


When a request is received, a cluster member uses multiple means to determine which cluster 


member is the authoritative server for the request. It looks for a parameter on the query string of the 
URL indicating the authoritative server. It looks for an HTTP cookie indicating the authoritative server. 
If these do not exist, the cluster member examines the payload of the HTTP request to determine the 
authoritative server. Payload examinations result in immediate identification of the authoritative server 
or a user session ID or user identity ID that can be used to locate the authoritative server. 


If a user session ID or user identity ID is found, the ID is broadcast to all cluster members asking 
which member is the authoritative server for the given ID. The authoritative server receives the 
broadcast message, determines that it indeed holds the given session or user, and responds 
accordingly. 


The higher the number of proxied requests, the lower the performance of the entire system. 
Furthermore, the higher the number of payload examinations and ID broadcasts, the lower the 
performance of the entire system. 


Statistic Description 


Currently Active Proxied 
Requests 


The number of currently active proxied HTTP requests. 


Total Proxied Requests The total number of proxied requests that have been processed, since Identity 
Server was started. These requests were sent to a non-authoritative (wrong) 


box. 


Total Non-Proxied Requests The total number of non-proxied requests that have been processed, since 
Identity Server was started. These requests were sent to the authoritative 


(correct) box. 
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Statistic 


Authoritative Server Obtained 
from URL Parameter 


Authoritative Server Obtained 
from Cookie 


Payload Examinations 
Successful Payload 
Examinations 

Identity ID Broadcasts 
Successful Identity ID 
Broadcasts 

Session ID Broadcasts 


Successful Session ID 
Broadcasts 


SP Brokering 


Statistic 


Total Brokering Requests 


Total Brokering Requests 
Denied Due to Group Check 


Total Brokering Requests 
Denied Due to Role Deny 


Total Brokering Requests 
Passed 


Description 


The total number of authoritative servers identified by using the parameter from 
the URL query string, since Identity Server was started. 


The total number of authoritative servers identified by using the HTTP cookie, 
since Identity Server was started. 


The total number of attempted payload examinations to identify the 
authoritative server, since Identity Server was started. 


The total number of successful payload examinations to identify the 
authoritative server, since Identity Server was started. 


The total number of attempted Identity ID Broadcasts to identify the 
authoritative server, since Identity Server was started. 


The total number of successful Identity ID Broadcasts to identify the 
authoritative server, since Identity Server was started. 


The total number of attempted Session ID Broadcasts to identify the 
authoritative server, since Identity Server was started. 


The total number of successful Session ID Broadcasts to identify the 
authoritative server, since Identity Server was started. 


Description 


The total number of brokering requests created after Identity Server was 
started. This count is a sum of all connections created to all replicas of the 
configuration datastore and all user stores. 


The total number of brokering authentication requests denied in a target 
service provider. The brokering group can either be the identity provider or 
target service provider but both does not belong to the same group. 


The total number of brokering authentication requests to a target service 
provider denied due to broker policy evaluation denying the role. 


The total number of brokering requests passed after Identity Server was 
started. 


Monitoring Access Gateway Cluster Statistics 


You can view and configure general performance statistics for the servers and service providers 
assigned to the selected cluster. 


Server Statistics 


On the Cluster Statistics page, you can configure the list of server statistics to show the desired 
statistics for an Access Gateway cluster. See “Server Activity Statistics” on page 1074 and “Server 
Benefits Statistics” on page 1079 for the complete list of statistics for each server in an Access 


Gateway cluster. 
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Perform the following steps: 
1 In Administration Console Dashboard, click Devices > Access Gateways > [Name of Cluster] > 
Statistics > Server Statistics. 
2 Click Configure. 


3 Select Set default statistics under Selected Statistics to replace the selected statistics with the 
default statistics. 


The default statistics include CPU Utilization, Current Connections to Origin Server, Current 
Connections to Browsers, Total Bytes per Second, Requests per Second to Origin Server, 
Requests per Second from Browsers, and Total Requests per Second. 


4 Select statistics from Available Statistics and move to Selected Statistics. 
5 Click OK. 


The Cluster Statistics page displays the summary of configured statistics for each individual 
member of the cluster. 


To view additional statistical information about a specific Access Gateway, click the name of 
Access Gateway in the Server Name column of the summary. 


You can also view all the statistics for an individual server of the cluster. Click View in the 
Statistics column of the summary to see these additional statistics. 


For more information, see Section 22.2.1, “Monitoring Access Gateway Statistics,” on 
page 1074. 


6 Click Close. 


NOTE: In the cluster level statistics, you can view the list of servers, which are associated with that 
cluster. If a statistics is not applicable for a particular Access Gateway server, the value of the 
statistics is displayed as Not Supported for that server. 


Service Provider Statistics 


On the Cluster Statistics page, you can configure the list of service provider statistics to show the 
desired statistics for an Access Gateway cluster. See “Service Provider Activity Statistics” on 
page 1079 for the complete list of statistics for each server in an Access Gateway cluster. 


Perform the following steps: 
1 In Administration Console Dashboard, click Devices > Access Gateways > [Name of Cluster] > 
Statistics > Service Provider Statistics. 
2 Click Configure. 


3 Select Set default statistics under Selected Statistics if you want to replace the selected 
statistics with the default statistics. 


The default statistics include Free Memory, Provided Authentications, Cached Sessions, Logins 
In Last Interval, Currently Active Requests - Incoming HTTP Requests, Currently Active 
Requests - Outgoing HTTP Requests, and Currently Active Proxied Requests. 


4 Select statistics from Available Statistics and move to Selected Statistics. 
5 Click OK. 


The Cluster Statistics page displays the summary of configured statistics for each individual 
member of the cluster. 


To view additional statistical information about a specific Access Gateway, click the name of 
Access Gateway in the Server Name column of the summary. 
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22.3.1 


22.3.1.1 


You can also view all the statistics for an individual server of the cluster. Click View in the 
Statistics column of the summary to see these additional statistics. 


For more information, see “Service Provider Activity Statistics” on page 1079. 
6 Click Close. 


Component Statistics Through REST APIs 


You can programmatically access statistics of Access Gateways, Identity Servers, and ESP. This 
section includes the following topics: 


¢ Section 22.3.1, “Monitoring API for Identity Server Statistics,” on page 1085 
¢ Section 22.3.2, “Monitoring API for Access Gateway Statistics,” on page 1090 


Monitoring API for Identity Server Statistics 


For programmatic access to Identity Server statistics, you must enable the Representational State 
Transfer (REST) API. 


To enable the REST API: 


1 Place the nidpmonitor. txt file in to the WEB- INF directory of Identity Server and ESP webapp. 


For Identity Server: 
Linux: /opt/novell/nam/idp/webapps/nidp/WEB- INF/ 
Windows: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEB- INF/ 
For ESP: 
Linux: /opt/novell/nam/mag/webapps/nesp/WEB- INF/ 
Windows: \Program Files\Novell\Tomcat\webapps\nesp\WEB-INF 
2 Add the following line in nidpmonitor . txt: 


urn:novell:nidp:monitor:anyaccess 


After this line, you must add the IP addresses of the servers from which you will be making calls 


to the REST API. Example content of the nidpmonitor.txt file: 
urn:novell:nidp:monitor:anyaccess 
10.0.0.0 
172.16.0.0 
3 Restart Identity Server. 


IMPORTANT: Frequent requests to get the statistics impact the system performance. It is 
recommended to keep a five minutes interval between every probe for the statistics. 


Endpoints of the REST API 


Identity Server uses this REST endpoint: https://<DNS FQDN of NIDP>:<port>/nidp/app/monitor. 
ESP uses this REST endpoint: https://<DNS FQDN of ESP>:<port>/nesp/app/monitor. 


The endpoint takes the following three parameters: 
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Parameter Value Description 


displayType XML This parameter specifies the output display 
type. Currently it supports only XML. 


command See Supported Commands and This specifies the monitored statistics that are 
Their Outputs for details of the to be displayed. 
commands that support this 
parameter. 


reset This parameter can take only This specifies the monitored statistics that is to 
"True" as value. See Supported be reset. 
Commands and Their Outputs 
for details of the commands 
which support reset. 


Supported Commands and Their Outputs 


The following list includes supported commands: 


+ httplnRequests 

¢ inUrlTypes 

+ httpOutRequests 

+ IdapServerConfig 

+ IdapConnections 

+ IdapConnectionWaits 
¢ IdapReplicaStats 

+ IdapPerfOverview 

¢ IdapFailOverview 

¢ authPerf 


NOTE: When using the curl command, place the URL inside double quotes (""). Otherwise, the XML 
data does not render. For example, curl -k "https://<domain>:<port>/nidp/app/ 
monitor?command=inUrlTypes&displayType=xml". 


httpInRequests 


This command supports reset. This command displays the monitored statistics of incoming HTTP 
requests to Identity Server. 


Example output: 


<?xml version="1.0" encoding="UTF-8"?><InComingHTTPRequests> <ThreadIntervals> 
<NamedValues> <NamedValue name="Total" value="61" /> <NamedValue name="Current 
Requests" value="1" /> </NamedValues> <ActiveObjects abandoned="0"> <ActiveObject 
name="ajp-bio-/127.0.0.1-9019-exec-23" age="3"> </ActiveObject> </ActiveObjects> 
<Historical> <Spectrometer dataPoints="22" totalCount="60" maxDataPoints="500"> 
<max>145</max> <min>1</min> <mean>18</mean> </Spectrometer> </Historical> </ 
ThreadIntervals></InComingHTTPRequests> 
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inUrlTypes 


This command supports reset. This command displays counts of the URL types and services that 
have been requested to Identity Server. 


Example output: 


<UrlTypes> <NamedValues> <NamedValue name="CMD: /app/, monitor" value="15" /> 
<NamedValue name="CMD: /app/, ping" value="13" /> <NamedValue name="CMD: /idff, 
soap" value="1" /> <NamedValue name="CMD: /idff, sso" value="4" /> <NamedValue 
name="JSP: content.jsp" value="1" /> </NamedValues></UrlTypes> 


httpOutRequests 


This command supports reset. This command displays the monitored statistics of outgoing HTTP 
requests from Identity Server. 


Example output: 


<?xml version="1.0" encoding="UTF-8"?><OutGoingHTTPRequests> <ThreadIntervals> 
<NamedValues> <NamedValue name="Total" value="25" /> </NamedValues> <Historical> 
<Spectrometer dataPoints="10" totalCount="25" maxDataPoints="500"> <max>51</max> 
<min>2</min> <mean>12</mean> </Spectrometer> </Historical> </ThreadIntervals></ 
OutGoingHTTPRequests> 


IdapServerConfig 


This command does not support reset. This command displays the setup details of Identity Server 
configuration store and the user store. 


Example output: 


<UserStoreManager id="MGf373f25e-5a95 -484e -85fe-2d3f073e3c28"> 
<TrustConfigDataStore> <UserStore id="USef25d609- 7577 -4bab-a705-f00b5406f2cc" 
systemId="cn=SCC7u0ouw, cn=cluster, cn=nids, ou=accessManagerContainer, o=novell" 
displayName=""_directoryName="Novell eDirectory" 
adminUserName="ou=nidsUser, ou=UsersContainer, ou=Partition, ou=PartitionsContainer,o 
u=VCDN_Root, ou=accessManagerContainer, o=novell" idleTimeout="10000" 
bindTimeout="0" allowRebind="true" maxwaitReservations="-1"> <Replicas> <Replica 
id="0c498978-2d16-4b25-ae41-484fca62fc36" 
systemId="PseudoXMLBasedUserStoreReplicaDNO" displayName="Replica 1" host="ldaps:/ 
/ 10.0.0.0" port="636" maxConnections="5" doSSL="true"> <ConnectionPool 
id="PL8928e311-6a84-494a-b61a-5ffF43005dd6f : 0c498978-2d16-4b25-ae41-484fca62fc36" 
adminUserName="ou=nidsUser, ou=UsersContainer, ou=Partition, ou=PartitionsContainer,o 
u=VCDN_Root, ou=accessManagerContainer, o=novell" maxConnections="5" skipCount="10" 
waitResTimeout="60000" waitResSleep="20" waitResSleepIterCount="3000" load="0"> 
<AdminConnections> <Connection id="Oadff495 -9321-485c -b156-66deceeefa84" 
type="admin" checkedOut="false" IdleAge="5985087" /> </AdminConnections> </ 
ConnectionPool> </Replica> </Replicas> </UserStore> </TrustConfigDataStore> 
<UserStores> <UserStore id="USc15e7906-d4a9- 41c3-8438-cd10fb6c7a89" 
systemId="cn=USmkp9m, cn=Alrre4, cn=SCC7uOouw, cn=cluster, cn=nids, ou=accessManagerCon 
tainer,o=novell" displayName="SingleBoxUserStore" directoryName="Novell 
eDirectory" adminUserName="cn=admin, o=novell" idleTimeout="10000" bindTimeout="0" 
allowRebind="true" maxwWaitReservations="-1"> <SearchContexts> <SearchContext 
order="0" scope="1" context="o=novell" /> </SearchContexts> <Replicas> <Replica 
id="0a307605-8946-4455-8080-f1819562481d" 
systemId="cn=USR1xnx69, cn=USmkp9m, cn=Alrre4, cn=SCC7uOouw, cn=cluster, cn=nids, ou=acc 
essManagerContainer, o=novell" displayName="SingleBoxUserStoreReplica" 
host="l1daps:// 10.0.0.0" port="636" maxConnections="20" doSSL="true"> 
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<ConnectionPool id="PLce0653bc - 488d -4e7c -81a5 -08e935d83c82 : 0a307605 - 8946 -4455- 
8080-f1819562481d" adminUserName="Ccn=admin, o=novell" maxConnections="20" 
skipCount="10" waitResTimeout="60000" waitResSleep="20" 
waitResSleepIterCount="3000" load="0"> <AdminConnections> <Connection 
id="b1c0a413 -2c36-4b64-831c-b0849421c7a0" type="admin" checkedOut="false" 
IdleAge="259357" /> </AdminConnections> </ConnectionPool> </Replica> </Replicas> 
</UserStore> </UserStores></UserStoreManager> 


IdapConnections 


This command does not support reset. This command displays counts of Identity Server LDAP 
connection. 


Example output: 


<LdapConnections> <TotalAdded admin="25" user="1" /> <TotalRemoved admin="23" 
user="1" /> <CurrentValidInUse admin="0" user="0" /> <CurrentValidOutOfUse 
admin="2" user="0" /> <CurrentInvalidEstd admin="0" user="0" /> 
<CurrentInvalidNonEstd admin="0" user="0" /> <TotalForceCloseSuccess admin="23" 
user="1" /> <TotalForceCloseError admin="0" user="0" /> <TotalForceCloseNonEstd 
admin="0" user="0" /></LdapConnections> 


IdapConnectionWaits 


This command supports reset. This command displays statistics of Identity Server LDAP connection 
wait time. 


Example output: 


<LDAPConnectionWaits></LDAPConnectionWaits> 


IdapReplicaStats 


This command does not support reset. This command displays statistics of Identity Server LDAP 
replica. 


Example output: 


<LdapReplicaStatsCollection> <TrustConfigDataStoreStats> <LdapReplicaStats 
displayName="Replica 1" host="l1daps:// 10.0.0.0 " inRestart="false" load="0"> 
<ExistingAdminConnectionReservation admin="97" /> <NewConnections admin="2" 
user="0" /> <Rebinds user="0" /> <InvalidRebinds user="0" /> <Waits admin="0" 
user="0" /> <WaitExpired admin="0" user="0" /> <WaitSkipped admin="0" user="0" /> 
<WaitHitMaxSkipped admin="0" user="0" /> </LdapReplicaStats> </ 
TrustConfigDataStoreStats> <LdapReplicaStats 
displayName="SingleBoxUserStoreReplica" host="ldaps://10.0.0.0" inRestart="false" 
load="0"> <ExistingAdminConnectionReservation admin="86" /> <NewConnections 
admin="28" user="1" /> <Rebinds user="0" /> <InvalidRebinds user="0" /> <Waits 
admin="0" user="0" /> <wWaitExpired admin="0" user="0" /> <WaitSkipped admin="0" 
user="0" /> <WaitHitMaxSkipped admin="0" user="0" /> </LdapReplicaStats></ 
LdapReplicaStatsCollection> 


IdapPerfOverview 


This command does not support reset. This command displays performance statistics of Identity 
Server LDAP replica. 


Example output: 
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<?xml version="1.0" encoding="UTF-8"?><LdapReplicaPer fCollection> 
<TrustConfigDataStorePerf> <LdapReplicaPerf displayName="Replica 1" 
inRestart="false" load="0" host="ldaps://10.0.0.0"> <All0psDuration> <Interval> 
<Spectrometer dataPoints="5" totalCount="6" maxDataPoints="300"> <max>46</max> 
<min>1</min> <mean>16</mean> </Spectrometer> </Interval> <Historical> 
<Spectrometer dataPoints="11" totalCount="100" maxDataPoints="500"> <max>93</max> 
<min>1</min> <mean>3</mean> </Spectrometer> </Historical> </All0psDuration> 
<CreateConnDuration> <Interval> <Spectrometer dataPoints="2" totalCount="2" 
maxDataPoints="300"> <max>46</max> <min>44</min> <mean>45</mean> </Spectrometer> 
</Interval> <Historical> <Spectrometer dataPoints="1" totalCount="1" 
maxDataPoints="500"> <max>93</max> <min>93</min> <mean>93</mean> </Spectrometer> 
</Historical> </CreateConnDuration> <CloseConnDuration> <Interval> <Spectrometer 
dataPoints="1" totalCount="2" maxDataPoints="300"> <max>1</max> <min>1</min> 
<mean>1</mean> </Spectrometer> </Interval> </CloseConnDuration> <SearchDuration> 
<Interval> <Spectrometer dataPoints="2" totalCount="2" maxDataPoints="300"> 
<max>3</max> <min>2</min> <mean>2</mean> </Spectrometer> </Interval> <Historical> 
<Spectrometer dataPoints="8" totalCount="95" maxDataPoints="500"> <max>11</max> 
<min>1</min> <mean>2</mean> </Spectrometer> </Historical> </SearchDuration> 
<GetDuration> <Historical> <Spectrometer dataPoints="4" totalCount="4" 
maxDataPoints="500"> <max>10</max> <min>1</min> <mean>6</mean> </Spectrometer> </ 
Historical> </GetDuration> <ModifyDuration></ModifyDuration> <CreateObjDuration></ 
CreateObjDuration> <DeleteObjDuration></DeleteObjDuration> <ExtDuration></ 
ExtDuration> <RebindDuration></RebindDuration> </LdapReplicaPerf> </ 
TrustConfigDataStorePerf> <LdapReplicaPerf displayName="SingleBoxUserStoreReplica" 
inRestart="false" load="0" host="l1daps://10.0.0.0"> <All0psDuration> <Interval> 
<Spectrometer dataPoints="5" totalCount="19" maxDataPoints="300"> <max>46</max> 
<min>1</min> <mean>13</mean> </Spectrometer> </Interval> <Historical> 
<Spectrometer dataPoints="5" totalCount="9" maxDataPoints="500"> <max>43</max> 
<min>0</min> <mean>5</mean> </Spectrometer> </Historical> </All0psDuration> 
<CreateConnDuration> <Interval> <Spectrometer dataPoints="2" totalCount="5" 
maxDataPoints="300"> <max>46</max> <min>45</min> <mean>45</mean> </Spectrometer> 
</Interval> <Historical> <Spectrometer dataPoints="1" totalCount="1" 
maxDataPoints="500"> <max>43</max> <min>43</min> <mean>43</mean> </Spectrometer> 
</Historical> </CreateConnDuration> <CloseConnDuration> <Interval> <Spectrometer 
dataPoints="1" totalCount="5" maxDataPoints="300"> <max>1</max> <min>1</min> 
<mean>1</mean> </Spectrometer> </Interval> </CloseConnDuration> <SearchDuration> 
<Interval> <Spectrometer dataPoints="2" totalCount="3" maxDataPoints="300"> 
<max>2</max> <min>1</min> <mean>1</mean> </Spectrometer> </Interval> </ 
SearchDuration> <GetDuration> <Interval> <Spectrometer dataPoints="2" 
totalCount="3" maxDataPoints="300"> <max>2</max> <min>1</min> <mean>1</mean> </ 
Spectrometer> </Interval> <Historical> <Spectrometer dataPoints="2" totalCount="4" 
maxDataPoints="500"> <max>2</max> <min>1</min> <mean>1</mean> </Spectrometer> </ 
Historical> </GetDuration> <ModifyDuration></ModifyDuration> <CreateObjDuration></ 
CreateObjDuration> <DeleteObjDuration></DeleteObjDuration> <ExtDuration> 
<Interval> <Spectrometer dataPoints="2" totalCount="2" maxDataPoints="300"> 
<max>2</max> <min>1</min> <mean>1</mean> </Spectrometer> </Interval> <Historical> 
<Spectrometer dataPoints="3" totalCount="4" maxDataPoints="500"> <max>3</max> 
<min>0</min> <mean>1</mean> </Spectrometer> </Historical> </ExtDuration> 
<RebindDuration> <Interval> <Spectrometer dataPoints="1" totalCount="1" 
maxDataPoints="300"> <max>3</max> <min>3</min> <mean>3</mean> </Spectrometer> </ 
Interval> </RebindDuration> </LdapReplicaPer f></LdapReplicaPerfCollection> 


IdapFailOverview 


This command does not support reset. This command displays statistics of Identity Server LDAP 
replica failure. 


Example output: 
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<?xml version="1.0" encoding="UTF-8"?><LdapReplicaFailureCollection> 
<TrustConfigDataStoreFailure> <LdapReplicaFailurePerf displayName="Replica 1" 
inRestart="false" load="0" host="ldaps://10.0.0.0"> <AllOpsDuration> <Historical> 
<Spectrometer dataPoints="2" totalCount="3" maxDataPoints="500"> <max>2</max> 
<min>1</min> <mean>1</mean> </Spectrometer> </Historical> </All0psDuration> 
<CreateConnDuration></CreateConnDuration> <CloseConnDuration></CloseConnDuration> 
<SearchDuration></SearchDuration> <GetDuration> <Historical> <Spectrometer 
dataPoints="2" totalCount="3" maxDataPoints="500"> <max>2</max> <min>1</min> 
<mean>1</mean> </Spectrometer> </Historical> </GetDuration> <ModifyDuration></ 
ModifyDuration> <CreateObjDuration></CreateObjDuration> <DeleteObjDuration></ 
DeleteObjDuration> <ExtDuration></ExtDuration> <RebindDuration></RebindDuration> 
</LdapReplicaFailurePerf> </TrustConfigDataStoreFailure> <LdapReplicaFailurePerf 
displayName="SingleBoxUserStoreReplica" inRestart="false" load="0" host="ldaps:// 
10.0.0.0"> <Al1lOpsDuration> <Interval> <Spectrometer dataPoints="2" totalCount="2" 
maxDataPoints="300"> <max>3054</max> <min>3051</min> <mean>3052</mean> </ 
Spectrometer> </Interval> </AllOpsDuration> <CreateConnDuration> <Interval> 
<Spectrometer dataPoints="2" totalCount="2" maxDataPoints="300"> <max>3054</max> 
<min>3051</min> <mean>3052</mean> </Spectrometer> </Interval> </ 
CreateConnDuration> <CloseConnDuration></CloseConnDuration> <SearchDuration></ 
SearchDuration> <GetDuration></GetDuration> <ModifyDuration></ModifyDuration> 
<CreateObjDuration></CreateObjDuration> <DeleteO0bjDuration></Delete0bjDuration> 
<ExtDuration></ExtDuration> <RebindDuration></RebindDuration> </ 
LdapReplicaFailurePerf></LdapReplicaFailureCollection> 


authPerf 


This command does not support reset. This command displays performance statistics of Identity 
Server local authentication. 


Example output: 


<?xml version="1.0" encoding="UTF-8"?><AuthenticationPerformance> <NamedValues> 
<NamedValue name="Provided Authentications" value="2" /> <NamedValue 
name="Consumed Authentications" value="3" /> <NamedValue name="Consumed 
Authentications Failures" value="6" /> <NamedValue name="Historical PEAK Logins" 
value="1" /> <NamedValue name="Logouts" value="2" /> </NamedValues> 
<LocalAuthDuration historicalMean="106" intervalMean="105"> <ContractStats 
name="Name/Password - Form"> <Historical> <Spectrometer dataPoints="1" 
totalCount="1" maxDataPoints="500"> <max>100</max> <min>100</min> <mean>100</mean> 
</Spectrometer> </Historical> </ContractStats> <ContractStats 
name="MyTwoContracts"> <Interval> <Spectrometer dataPoints="1" totalCount="1" 
maxDataPoints="300"> <max>105</max> <min>105</min> <mean>105</mean> </ 
Spectrometer> </Interval> <Historical> <Spectrometer dataPoints="1" totalCount="1" 
maxDataPoints="500"> <max>113</max> <min>113</min> <mean>113</mean> </ 
Spectrometer> </Historical> </ContractStats> </LocalAuthDuration> </ 
AuthenticationPerformance> 


22.3.2 Monitoring API for Access Gateway Statistics 


For programmatic access to Access Gateway statistics, you require to enable the global advanced 
option NAGStatsClientIPWhitelist. This option takes a list of IP addresses of servers that can access 
Access Gateway statistics. 


To access the statistics, run the HTTP GET command on the resource: https://<mag-host-name>/ 
mag-stats. 
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NOTE: Frequent requests to get the statistics impact the system’ performance. It is recommended to 
keep a five minutes interval between every probe for the statistics. 


To enable this option: 


1 In Administration Console Dashboard, select Devices > Access Gateway Servers > Edit > 


Advanced Options. 


2 Add this line: NAGStatsClientIPwhitelist <ip1> <ip2>. 


3 Replace <ip1> and <ip2> with the IP addresses of the servers from which you want to access 
the statistics. 


4 Click OK. 


This request displays the following: 


¢ Https related statistics 


+ 


+ 


Requests received 
Active requests 


+ Server related statistics 


+ 


+ 


+ 


+ 


+ 


+ 


Product start time 
Product up time 
Product CPU utilization 
Disk swap (KB) 

Disk swap used (KB) 
Memory total (KB) 


+ Cache statistics 


NOTE: Cache statistics are 0 because they are not implemented currently in the server side. 


+ 


+ 


+ 


+ 


Cache stats (KB) 

Cache stats utilization percentage 
Cache hit ratio since last reset 
Cache stats object count 


¢ Summary Statistics Byte 


+ 


+ 


+ 


+ 


+ 


+ 


Total bytes sent to the origin server 
Total bytes read from the Web server 
Total bytes sent to the browsers 

Total bytes received from the browsers 
Bytes per sec read from the Web server 
Bytes per sec sent to the browsers 


¢ Summary Statistics Benefits 


+ 


+ 


Total bytes saved 
Total bytes saved per second 


Example output: 
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<?xml version="1.0" encoding="UTF-8"?><MAGStatistics><httpStats> <NamedValues> 
<NamedValue name="RequestsReceived" value="0" /> <NamedValue name="ActiveRequests" 
value="1" /> </NamedValues></httpStats><boxStats> <NamedValues> <NamedValue 
name="ProductStartTime" value="Fri, 27 Jul 2012 11:01:11 GMT"/> <NamedValue 
name="ProductUpTime" value="0:0:0:26" /> <NamedValue name="ProductCPUUtilization" 
value="-294" /> <NamedValue name="DiskSwapkb" value="4088532" /> <NamedValue 
name="DiskSwapUsedKb" value="0" /> <NamedValue name="MemoryTotalkKb" value="7835" / 
> </NamedValues></boxStats><cacheStats> <NamedValues> <NamedValue 
name="cacheStatsKb" value="0" /> <NamedValue name="cacheStatsUtilPercentage" 
value="0" /> <NamedValue name="cacheHitRatioSinceReset" value="0" /> <NamedValue 
name="cacheStatsObjectCount" value="0" /> </NamedValues></ 
cacheStats<summaryStatsByte> <NamedValues> <NamedValue 
name="TotalBytesSentToOriginServer" value="0" /> <NamedValue 
name="TotalBytesReadFromwS" value="0" /> <NamedValue 
name="TotalBytesSentToBrowsers" value="0" /> <NamedValue 
name="TotalBytesReceivedFromBrowsers" value="0" /> <NamedValue 
name="BytesPsecReadFromwS" value="0" /> <NamedValue name="BytesPsecSentToBrowsers" 
value="0" /> </NamedValues></summaryStatsByte><summaryStatsBenefits> <NamedValues> 
<NamedValue name="TotalBytesSaved" value="0" /> <NamedValue 
name="TotalBytesSavedPerSecond" value="0" /> </NamedValues></ 
summaryStatsBenefits><summaryStatsRequests> <NamedValues> <NamedValue 
name="TotalRequestsPSecBrowsers" value="0" /> <NamedValue 
name="PeakTotalRequestsPSecBrowsers" value="1" /> <NamedValue 
name="TotalRequestsPSecOriginServer" value="0" /> <NamedValue 
name="PeakTotalRequestsPSecOriginServer" value="0" /> <NamedValue 
name="CurrentTotalRequestsToOriginServer" value="0" /> <NamedValue 
name="CurrentTotalRequestsReceivedFromBrowser" value="1" /> <NamedValue 
name="FailedRequestsTowS" value="0" /> <NamedValue name="CumulativeRequestsTowS" 
value="0" /> </NamedValues></summaryStatsRequests><summaryStatsConnections> 
<NamedValues> <NamedValue name="CurrentConnectionsBrowser" value="10" /> 
<NamedValue name="CurrentConnectionsBackend" value="0" /> <NamedValue 
name="TotalConnectionsBrowser" value="28" /> <NamedValue 
name="TotalConnectionsBackend" value="0" /> <NamedValue 
name="PeakConnectionsBrowser" value="6" /> <NamedValue 
name="PeakConnectionsBackend" value="0" /> <NamedValue 
name="FailedConnectionsBackend" value="0" /> </NamedValues></ 
summaryStatsConnections></MAGStatistics> 
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Monitoring Component Command 
Status 


Commands are issued to a component when you make configuration changes and when you select 
an action such as stopping or starting that component. The command status only displays the 
commands of certificates that are associated with a device. 


Certain commands, such as start and stop, retry up to 10 times before they fail. The first few retries 
are spaced a few minutes apart, then they move to 10-minute intervals. These commands can take 
over an hour to result in a failure. As long as the command is in the retry cycle, the command has a 
status of pending. 

¢ If you do not want to wait for the cycle to complete, you need to manually delete the command. 


¢ If you enter the same command and it succeeds before the first command has completed its 
retry cycle, the first command always stays in the pending state. You need to manually delete the 
command. 


The Command Status page lists scheduled events and the current status of each event. A new 
command appears in the list each time you change a configuration. The commands remain listed until 
you delete them. 


This section discusses the following topics: 


¢ Section 23.1, “Viewing the Command Status of Identity Server,” on page 1093 

¢ Section 23.2, “Viewing the Command Status of Access Gateway,” on page 1094 

¢ Section 23.3, “Viewing the Command Status of the Analytics Server,” on page 1096 
¢ Section 23.4, “Reviewing the Command Status for Certificates,” on page 1097 


23.1 Viewing the Command Status of Identity Server 


This section describes the following tasks related to commands: 


¢ Section 23.1.1, “Viewing the Status of Current Commands,” on page 1093 
¢ Section 23.1.2, “Viewing Detailed Command Information,” on page 1094 


23.1.1 Viewing the Status of Current Commands 


1 In Administration Console Dashboard, click Devices > Identity Servers. 
2 Click the Command Status link for the server. 

3 To delete a command, select it and click Delete. 

4 Click Refresh to refresh the display. 
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The following table describes the columns on the Command Status page: 


Column Name Description 

Name Lists Identity Server name. 

Status Lists the status of each server. 

Type Displays type of command issued to the server. 

Admin Displays the credentials of the administrator who performed the command. 
Date & Time The date and time that the command was issued. Date and time entries are 


specified in the local time. 


23.1.2 Viewing Detailed Command Information 


To view information about an individual command: 


1 Click Devices > Identity Servers > [Name of Server] > Command Status. 
2 Click the name of a command to get detailed information. The following information is displayed: 
Name: Identity Server name. 
Type: The type of command issued to the server. 
Admin: The distinguished name of the admin user who performed the command. 
Status: The status of the server command. 
Last Executed On: The date and time that the command was executed. 
3 To determine if any problems occurred, view the Command Execution Details section. 


For a command that fails because Administration Console cannot communicate with Identity 
Server, the page displays the following additional fields: 


Number of Tries: Specifies the number of times the command was executed. 
Command Try Log: Lists each try and the results. 
4 Select one of the following actions: 
+ Delete: To delete a command, click Delete. Click OK in the confirmation dialog box. 
+ Refresh: To update the current cache of recently executed commands, click Refresh. 
5 Click Close to return to the Command Status page. 


23.2 Viewing the Command Status of Access Gateway 


This section describes the following tasks related to commands: 


¢ Section 23.2.1, “Viewing the Status of Current Commands,” on page 1094 
¢ Section 23.2.2, “Viewing Detailed Command Information,” on page 1095 


23.2.1 Viewing the Status of Current Commands 


1 Click Devices > Access Gateways > [Name of Server] > Command Status. 
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Column Name Description 


Name Specifies name of the command. Click the link to view additional details about the 
command. For more information, see Section 23.2.2, “Viewing Detailed Command 
Information,” on page 1095. 


Status Specifies status of the command. Some of the possible states of the command include 
Pending, Incomplete, Executing, and Succeeded. 


Type Specifies the type of command. 


Admin Specifies if the system or a user issued the command. If a user issued the command, the 
DN of the user is displayed. 


Date & Time Specifies the local date and time the command was issued. 


2 Select one of the following actions: 
+ To view information about a particular command, click the name of a command. 
+ To delete a command from the list, select the command, then click Delete. 
+ To refresh the status of the listed commands, click Refresh. 

3 Click Close. 


23.2.2 Viewing Detailed Command Information 


1 Click Devices > Access Gateways > [Name of Server] > Command Status. 
2 Click the name of a command to get detailed information. 
The following command information is listed: 
Name: Specifies the display name that has been given to the command. 
Type: Specifies the type of command. 


Admin: Specifies whether the system or a user issued the command. If a user issued the 
command, the field contains the DN of the user. 


Status: Specifies the status of the command, and includes such states as Pending, Incomplete, 
Executing, and Succeeded. 


Last Executed On: Specifies when the command was issued. The date and time are displayed 
in local time. If the command failed, additional information is available. 


For a command that Administration Console can successfully send to Access Gateway, the page 
displays a Command Execution Details section with the name of the command and the 
command results. 


For a command that fails because Administration Console cannot communicate with Access 
Gateway, the page displays the following additional fields: 


Number of Tries: Specifies the number of times the command was executed. 
Command Try Log: Lists each try and the results. 
3 You can delete a command or update the current cache of recently executed commands. 
4 Click Close to return to the Command Status page. 
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23.3 Viewing the Command Status of the Analytics 
Server 


This section describes the following tasks related to commands: 


¢ Section 23.3.1, “Viewing the Status of Current Commands,” on page 1096 
¢ Section 23.3.2, “Viewing Detailed Command Information,” on page 1096 


23.3.1 Viewing the Status of Current Commands 


1 Click Devices > Analytics Server > [Name of Server] > Command Status. 


Column Name Description 


Name Specifies name of the command. Click the link to view additional details about the 
command. For more information, see Section 23.2.2, “Viewing Detailed Command 
Information,” on page 1095. 


Status Specifies status of the command. Some of the possible states of the command include 
Pending, Incomplete, Executing, and Succeeded. 


Type Specifies the type of command. 


Admin Specifies if the system or a user issued the command. If a user issued the command, the 
DN of the user is displayed. 


Date & Time Specifies the local date and time the command was issued. 


2 Select one of the following actions: 
+ To view information about a particular command, click the name of a command. 
+ To delete a command from the list, select the command, then click Delete. 
+ To refresh the status of the listed commands, click Refresh. 

3 Click Close. 


23.3.2 Viewing Detailed Command Information 


1 Click Devices > Analytics Server > [Name of Server] > Command Status. 
2 Click the name of a command to get detailed information. 
The following command information is listed: 
Name: Specifies the display name that has been given to the command. 
Type: Specifies the type of command. 


Admin: Specifies whether the system or a user issued the command. If a user issued the 
command, the field contains the DN of the user. 


Status: Specifies the status of the command, and includes such states as Pending, Incomplete, 
Executing, and Succeeded. 


Last Executed On: Specifies when the command was issued. The date and time are displayed 
in local time. If the command failed, additional information is available. 


For a command that fails because Administration Console cannot communicate with the 
Analytics Server, the page displays the following additional fields: 
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Number of Tries: Specifies the number of times the command was executed. 
Command Try Log: Lists each try and the results. 
3 You can delete a command or update the current cache of recently executed commands. 
4 Click Close to return to the Command Status page. 


23.4 Reviewing the Command Status for Certificates 


The command status displays only commands of certificates that are associated with a device. You 
can view the status of the commands that have been sent to the certificate server for execution. 
1 In Administration Console Dashboard, click Security > Certificates, then click Command Status. 
2 Use the following options to review or change a server's certificate command status: 


+ Delete: To delete a command, select the check box for the command, then click Delete. The 
selected command is cleared. 


+ Refresh: Click Refresh to update the current cache of recently executed commands. 
+ Name: Click this box to select all the commands in the list, then click Refresh or Delete. 
The following table describes the features on this page: 


Column Name Description 


Name Contains the display name of the command. Click the link to view additional details about 
the command. 


Status Specifies the status of the command. Some of the possible states of the command 
include Pending, Incomplete, Executing, and Succeeded. 


Type Specifies the type of server, such as Identity Server or Access Gateway. 


Commands Specifies the command given, such as Import certificate, or Import trusted 
root. 


Admin Specifies if the system or a user issued the command. If a user issued the command, the 
DN of the user is displayed. 


Date & Time Specifies the local date and time the command was issued. 


3 To review command information, click a link under the Name column. 


This page displays status information about the command and allows you to perform the 
following tasks: 


Refresh: Select this option to refresh the data for this command. 
Delete: Select this option to clear this command. 

The following command information is listed: 

Name: Specifies the display name that has been given to the command. 
Type: Specifies the type of command. 


Admin: Specifies whether the system or a user issued the command. If a user issued the 
command, the field contains the DN of the user. 


Status: Specifies the status of the command, and includes such states as Pending, Incomplete, 
Executing, and Succeeded. 


Last Executed On: Specifies when the command was issued. The date and time are displayed 
in local time. If the command failed, additional information is available. 
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For a command that Administration Console can successfully process, the page displays a 
Command Execution Details section with the name of the command and the command results. 


4 Click Close. 
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Monitoring Server Health 


You can monitor all components hosted by a server and quickly isolate and correct server issues. The 
system displays statuses (green, yellow, white, or red) for Access Manager components. You can 
access the health information at the following places: 


+ 


Dashboard 


The Dashboard page shows the heath status at the component-level. 
Auditing > Device Health 

The Device Health page shows the health status for all devices in one list. 
Devices > [Component] 


The Servers page for each component provides a health status for each device. 


Section 24.1, “Health States,” on page 1099 

Section 24.2, “Monitoring Health by Using the Hardware IP Address,” on page 1100 
Section 24.3, “Monitoring Health of Identity Servers,” on page 1100 

Section 24.4, “Monitoring the Health of Access Gateways,” on page 1102 

Section 24.5, “Monitoring the Health of Analytics Server,” on page 1107 


24.1 Health States 


The Health page displays the current status of the server. The following states are possible: 


Icon 


e 


@ 


& 


GA 


Description 


A green status indicates that the server has not detected any problems. 


A green status with a yellow diamond indicates that the server has not detected any problems but 
the configuration is not’ completely up-to-date because commands are pending. 


A green status with a red x indicates that the server has not detected any problems but that the 
configuration might not be what you want because one or more commands have failed. 


A red status with a bar indicates that the server has been stopped. 


A white status with disconnected bars indicates that the server is not communicating with 
Administration Console. 


A yellow status indicates that the server might be functioning sub-optimally because of 
configuration discrepancies. 


A yellow status with a question mark indicates that the server has not been configured. 


A red status with an x indicates that the server configuration might be incomplete or wrong, that a 
dependent service in not running or functional, or that the server is having a runtime problem. 
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24.2 Monitoring Health by Using the Hardware IP 


Address 


The Hardware IP Address page allows you to view the devices and agents managed through the 
selected IP address. You can monitor all of the devices hosted by a server and quickly isolate and 
correct server issues. The system displays statuses (green, yellow, white, or red) for the Access 
Manager devices. 
1 In Administration Console Dashboard, click Auditing > Device Health. 
2 To view information about the health of each installed device, click an IP address. 
3 Select one of the following actions: 
¢ To return to the Device Health page, click Close. 
+ To edit the details of a device, click the server name. 
+ To view health details, click the Health icon. 
+ To view the alerts, click the alerts link. 
+ To view device statistics, click the statistics link. 
+ To view or configure audit events for the device, click the Edit Events link. 


24.3 Monitoring Health of Identity Servers 


This section discusses the following topics: 


¢ Section 24.3.1, “Monitoring the Health of an Identity Server,” on page 1100 
¢ Section 24.3.2, “Monitoring the Health of a Cluster,” on page 1102 


24.3.1 Monitoring the Health of an Identity Server 


1100 


To view detailed health status information for an Identity Server: 
1 In Administration Console Dashboard, click Devices > Identity Servers > [Name of Server] > 
Health. 


The status icon is followed by a description that explains the significance of the current state. For 
more information about the icons, see Section 24.1, “Health States,” on page 1099. 


2 To ensure that the information is current, select one of the following: 


¢ Click Refresh to refresh the page with the latest health available from Administration 
Console. 


+ Click Update from Server to send a request to Identity Server to update its status 
information. This can take a few minutes. 
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3 Examine the Services Detail section that displays the status of each service. For an Identity 


Server, this includes information such as the following: 


Status Category 


Status: Indicates whether Identity Server is online 
and operational. 


Services: Indicates the general health of all 
configured services. 


Identity Server Configuration: Indicates the 
status of the configuration. 


Configuration Datastore: Indicates the status of 
the installed configuration datastore. 


User Datastores: Indicates whether Identity Server 
can communicate with the user stores, authenticate 
as the admin user, and find the search context. 


Signing, Encryption and SSL Connector Keys: 


Indicates whether these keystores contain valid a 
key. 


System Incoming and Outgoing HTTP 
Requests: Appears when throughput is slow. This 
health check monitors incoming HTTP requests, 
outgoing HTTP requests on the SOAP back 
channel, and HTTP proxy requests to cluster 
members. If one or more requests remain in the 
queue for over 2 minutes, this health check 
appears. 


SSL Communication: Indicates whether SSL 
communication is operating correctly. This health 
check appears only when the SSL communication 
check fails. 


If not healthy 


Verify whether Identity Server has been stopped or 
is not configured. 


Also verify that network problems are not interfering 
with communications between Identity Server and 
Administration Console. 


If one service is unhealthy, this category reflects 
that status. See the particular service that also 
displays an unhealthy status. 


Configure Identity Server or assign the server to a 
configuration.See,Section 3.3, “Configuring an 
Identity Server,” on page 59 


You might need to restart Tomcat or reinstall 
Administration Console. 


If you have a backup Administration Console, you 
can restore it. See Chapter 28, “Back Up and 
Restore,” on page 1129. 


If you don’t have a backup, you can try repairing the 
configuration datastore. See Section 30.1.8, 
“Repairing the Configuration Datastore,” on 

page 1164. 


If you want to convert a secondary console to your 
primary console, see Section 30.1.7, “Converting a 
Secondary Administration Console into a Primary 
Console,” on page 1156. 


Ensure that the user store is operating and 
configured correctly. You might need to import the 
SSL certificate for communication with Identity 
Server. See Section 5.1.1, “Configuring Identity 
User Stores,” on page 360. 


Click Identity Servers > Edit > Security and 
replace any missing or expired keys. 


Verify that all members of the cluster have sufficient 
bandwidth to handle requests. If a cluster member 
is going down, the problem resolves itself as other 
members of the cluster are informed that the 
member is down. 


If a cluster member is slow because it does not’ 
have enough physical resources (speed or memory) 
to handle the load, upgrade the hardware. 


Check SSL connectivity. Check for expired SSL 
certificates. 
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Status Category If not healthy 


Audit Logging Server: Indicates whether the audit Check the network connection between Identity 
agent is functioning and able to log events to the Server and the auditing server. 


auditing server. , 
See “Troubleshooting Novell Audit” (http:// 


Auditing must be enabled on Identity Server to www.novell.com/documentation/novellaudit20/ 
activate this health check (click Devices > Identity novellaudit20/data/al0lh30.html). 
Servers > Edit > Auditing and Logging). 


4 Click Close. 


24.3.2 Monitoring the Health of a Cluster 


The health page displays the current health of the cluster. 
1 In Administration Console Dashboard, click Devices > Identity Servers > [Name of Cluster] > 
Health. 


The status icon is followed by a description that explains the significance of the current state. For 
more information about the icons, see Section 24.1, “Health States,” on page 1099. 


2 To ensure that the information is current, click Refresh to refresh the page with the latest health 
available from Administration Console. 


3 To view health details about a specific member of the cluster, click the server's health icon. 


24.4 Monitoring the Health of Access Gateways 


This section discusses the following topics: 


¢ Section 24.4.1, “Monitoring the Health of an Access Gateway,” on page 1102 
¢ Section 24.4.2, “Monitoring the Health of an Access Gateway Cluster,” on page 1107 


24.4.1 Monitoring the Health of an Access Gateway 
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To view detailed health status information of an Access Gateway: 
1 In Administration Console Dashboard, click Devices > Access Gateways > [Name of Server] > 
Health. 


The status icon is followed by a description that explains the significance of the current state. For 
more information about these icons, see Section 24.1, “Health States,” on page 1099. 


2 To ensure that the information is current, select one of the following: 


¢ Click Refresh to refresh the page with the latest health available from Administration 
Console. 


¢ Click Update from Server to send a request to Access Gateway to update its status 
information. If you have made changes that affect the health of Access Gateway, select this 
option. Otherwise, it can take up to five minutes for the health status to change. 
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3 Examine the Services Detail section that displays the status of each service. For an Access 
Gateway, this includes information such as the following: 


+ “Service Categories of Access Gateway Appliance” on page 1103 


« “Service Categories of Access Gateway Service” on page 1105 


4 Click Close. 


Service Categories of Access Gateway Appliance 


Service Category 


Time: Indicates the type of time configuration. Time 
must be configured so that it remains synchronized 
with the other servers in the configuration 


Gateway: Specifies the type of routing that is 
configured for the gateway. 


DNS: Specifies whether the domain name server has 
been configured 


Services: Indicates the general health of all 
configured services. 


Address: Indicates whether an IP address has been 
configured for the reverse proxy to listen on. This is 
required for Access Gateway to function. 


Embedded Service Provider Communication: 


Indicates whether the Embedded Service Provider can 
communicate with Identity Server. 


If Not Healthy 


See Section 4.2.6, “Setting the Date and Time,” on 
page 318. 


See “Viewing and Modifying Gateway Settings” on 
page 321. 


Displays the IP address of the each configured DNS 
server and when the server last responded. 


See “Viewing and Modifying DNS Settings” on 
page 322. 


Displays messages about the health of the reverse 
proxy, the back end Web servers, and internal services 
(the SOAP back channel and the communication 
module). 


See “Creating a Proxy Service” on page 121. 


Restart the Embedded Service Provider. If restarting 
the Embedded Service Provider fails, try restarting 
Tomcat. 
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Service Category 


L4 and Cache: The L4 status indicates whether 
Access Gateway is responding to health checks from 
the L4 switch. The number increments with each 
health check for which Access Gateway does not send 
a response. 


+ When it reaches 13, the health is changed to 
yellow. 


+ When it reaches 31, the health is changed to red. 


If Access Gateway recovers and starts responding, the 
health turns green after 20 seconds and the 
unresponsive count is reset to 0. 


To fix the problem if it does not resolve itself, restart 
Access Gateway. 


The cache status indicates the current number of 
delayed cache requests and whether enough memory 
is available to process new requests. 


+ When this number reaches 101, the health is 
changed to yellow. 


+ When this number reaches 151, the health 
changes to red. To solve the problem, you need 
to restart Access Gateway. 


Embedded Service Provider Configuration: 


Indicates whether Access Gateway has been 
configured to trust an Identity Server and whether that 
configuration has been applied. 


At least one Identity Server must be configured and 
set up as a trusted authentication source for Access 
Gateway. 


A green status indicates that a configuration has been 
applied; it does not indicate that it is a functioning 
configuration. 


Configuration Datastore: Indicates whether the 
configuration datastore is functioning correctly. 


Clustering: Indicates whether all the cluster members 
are active and processing requests. 


Signing, Encryption and SSL Connector Keys: 


Indicates whether these keystores contain valid a key. 
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If Not Healthy 


Restart Access Gateway by entering the following 
commands: 


/etc/init.d/novell-apache2 stop and /etc/ 
init.d/novell-apache2 start OR rcnovell- 
apache2 stop and rcnovell-apache2 start 


See Section 3.8.2, “Managing Reverse Proxies and 
Authentication,” on page 119 for information about 
assigning an Identity Server configuration to Access 
Gateway. 


Restore the configuration datastore. See 
Section 30.1.8, “Repairing the Configuration 
Datastore,” on page 1164. 


Restart the cluster members that are not active or 
remove them from the cluster. 


Click Access Gateways > Edit > Service Provider 
Certificates and replace any missing or expired keys. 


24.4.1.2 


Service Category 


System Incoming and Outgoing HTTP Requests: 


Appears when throughput is slow. This health check 
monitors incoming HTTP requests, outgoing HTTP 
requests on the SOAP back channel, and HTTP proxy 
requests to cluster members. If one or more requests 
remain in the queue for over 2 minutes, this health 
check appears. 


TCP Listener(s): Indicates whether the listening port 
for the Embedded Service Provider is healthy. 


Embedded Service Provider’s Trusted Identity 
Provider: Indicates whether the configuration that 
Access Gateway trusts has been configured to contain 
at least one Identity Server. 


Audit Logging Server: Indicates whether the audit 
agent is functioning and able to log events to the 
auditing server. 


Auditing must be enabled on Identity Server to activate 
this health check (click Devices > Identity Servers > 
Edit > Auditing and Logging). 


If Not Healthy 


Verify that all members of the cluster have sufficient 
bandwidth to handle requests. If a cluster member is 
going down, the problem resolves itself as other 
members of the cluster are informed that the member 
is down. 


If a cluster member is slow because it does’not have 
enough physical resources (speed or memory) to 
handle the load, upgrade the hardware. 


Restart Access Gateway. 


Modify Identity Server configuration and add an 
Identity Server. See “Assigning an Identity Server to a 
Cluster Configuration” on page 71 


Configure Access Gateway to trust an Identity Server 
configuration. See Section 3.8.2, “Managing Reverse 
Proxies and Authentication,” on page 119. 


Check the network connection between Identity Server 
and the auditing server. 


See “Troubleshooting Novell Audit” (http:// 
www.novell.com/documentation/novellaudit20/ 
novellaudit20/data/al0lh30.html). 


Service Categories of Access Gateway Service 


Service Category 


Reverse Proxy - <Proxy Service Name>: Indicates 
the general health of all configured proxy services. A 
separate row is created for each proxy service. 


AGM - Configuration: Indicates whether all 
configuration changes have been applied. 


If Not Healthy 


Check the health of the Web server. 


Do the following: 


+ To re-push the current configuration, click 
Troubleshooting, select the gateway from the 
list of the Current Access Gateway 
Configurations, then click Re-push Current 
Configuration. 


+ To revert to last applied configuration, click 
Devices > Access Gateways > Edit, then click 
Revert. 


If these options do not fix the problem, view the 
Apache error .log file to discover the cause. The 
file is located in the following directory: 


Linux: /var/log/novell-apache2/ 


Windows: \Program 
Files\Novell\apache\logs\ 
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Service Category If Not Healthy 


TCP Listener - </P Address:Port>: Indicates whether 
Access Gateway Service is listening on the specified 
port. A separate row is created for each port the 
Gateway Service is configured to listen on. 


Restart the Apache service. 


ApacheGateway.log: Appears when Access Gateway 
Service is not healthy. It displays the latest error from 
the Apache error. log file. 


For more information about the problem, view the 
error . log file in the following directory: 


Linux: /var/log/novell-apache2/ 


Windows: \Program 
Files\Novell\apache\logs\ 


Embedded Service Provider Configuration: See Section 3.8.2, “Managing Reverse Proxies and 
Authentication,” on page 119 for information about 
assigning an Identity Server configuration to Access 


Gateway. 


Indicates whether Access Gateway has been 
configured to trust an Identity Server and whether that 
configuration has been applied. 


At least one Identity Server must be configured and set 
up as a trusted authentication source for Access 
Gateway. 


A green status indicates that a configuration has been 
applied; it does not indicate that it is a functioning 
configuration. 


Restore the configuration datastore. See 
Section 30.1.8, “Repairing the Configuration 
Datastore,” on page 1164. 


Configuration Datastore: Indicates whether the 
configuration datastore is functioning correctly. 


Restart the cluster members that are not active or 
remove them from the cluster. 


Clustering: Indicates whether all the cluster members 
are active and processing requests. 


Signing, Encryption and SSL Connector Keys: Click Access Gateways > Edit > Service Provider 


Certificates and replace any missing or expired 


Indicates whether these keystores contain a valid key. 


System Incoming and Outgoing HTTP Requests: 


Appears when throughput is slow. This health check 
monitors incoming HTTP requests, outgoing HTTP 
requests on the SOAP back channel, and HTTP proxy 
requests to cluster members. If one or more requests 
remain in the queue for over 2 minutes, this health 
check appears. 


TCP Listener(s): Indicates whether the listening port 
for the Embedded Service Provider is healthy. 


Embedded Service Provider’s Trusted Identity 
Provider: Indicates whether the configuration that 


Access Gateway trusts has been configured to contain 


at least one Identity Server. 
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keys. 


Verify that all members of the cluster have sufficient 
bandwidth to handle requests. If a cluster member is 
going down, the problem resolves itself as other 
members of the cluster are informed that the member 
is down. 


If a cluster member is slow because it does not’ have 
enough physical resources (speed or memory) to 
handle the load, upgrade the hardware. 


Restart Access Gateway. 


Modify Identity Server configuration and add an 
Identity Server. 


Configure Access Gateway to trust an Identity Server 
configuration. See “Creating a Proxy Service” on 
page 121. 


Service Category If Not Healthy 


Audit Logging Server: Indicates whether the audit Check the network connection between Identity 
agent is functioning and able to log events to the Server and the auditing server. 


auditing server. 
See “Troubleshooting Novell Audit” (http:// 


Auditing must be enabled on Identity Server to activate }=www.novell.com/documentation/novellaudit20/ 
this health check (click Devices > Identity Servers > _ novellaudit20/data/al0Ih30.html). 
Edit > Auditing and Logging). 


24.4.2 Monitoring the Health of an Access Gateway Cluster 


The Health icon on the cluster row displays the status of the least healthy member of the cluster. For 
information about the meaning of health icons, see Section 24.1, “Health States,” on page 1099. 


To view details about the status of the cluster: 


1 In Administration Console Dashboard, click Devices > Access Gateways. 
2 On the cluster row, click the Health icon. 
3 To ensure that the information is current, click Refresh. 


4 To view specific information about the status of an Access Gateway, click the Health icon in 
Access Gateway row. 


24.5 Monitoring the Health of Analytics Server 


This section discusses the following topics: 


¢ Section 24.5.1, “Monitoring the Health of Analytics Server,” on page 1107 
¢ Section 24.5.2, “Monitoring the Health of Analytics Server Cluster,” on page 1108 


24.5.1 Monitoring the Health of Analytics Server 


To view detailed health status information of Analytics Server: 
1 In Administration Console Dashboard, click Devices > Analytics Servers > [Name of Server] > 
Health. 


The status icon is followed by a description that explains the significance of the current state. For 
more information about these icons, see Section 24.1, “Health States,” on page 1099. 


2 To ensure that the information is current, select one of the following: 


+ Click Refresh to refresh the page with the latest health available from Administration 
Console. 


+ Click Update from Server to send a request to Analytics Server to update the status of the 
health of the server. If you have made changes that affect the health of the Analytics Server, 
select this option. Otherwise, it can take up to five minutes for the health status to change. 


3 Examine the Services Detail section that displays the status of each service. For Analytics 
Server, this includes the following information: 
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Service Category If Not Healthy 


Dashboard Server: Indicates whether the server Restart Analytics Dashboard service. 


for Analytics Dashboard is functioning properly. 
/etc/init.d/novell-dashboard stop 


This service is used for displaying Analytics /etc/init.d/novell-dashboard start 


dashboard. . : : 
NOTE: The device health is determined from 


Dashboard service. If this service is stopped, 
Administration Console fails to get the health 
information of the device. Hence, the health status 
is displayed as Non-reporting. 


Real-time Aggregator: Indicates that the data is Restart the real-time aggregator service. 


aggregated from the events that are generated in 
real-time. /etc/init.d/novell-realtime stop 


/etc/init.d/novell-realtime start 
This service will retrieve data from events that are 
required for displaying the real-time graphs. 


Offline Aggregator: Indicates that the data is Restart the offline aggregator service. 


aggregated from the historic or older events. 
/etc/init.d/novell-offline stop 


This service will schedule, and generate data for etc/init.d/novell-offline start 
historic graphs. 


ElasticSearch DB: Indicates that all the Restart the Elastic Search database service. 


aggregated data is stored in Elastic Search. 
/etc/init.d/sentinel stopSIdb 


This service is used for data indexing. /etc/init.d/sentinel startSIdb 
Sentinel Server: Indicates that the audit events are Restart the Sentinel Server. 


sent from Access Manager components to Sentinel 
server. /etc/init.d/sentinel stop 


/etc/init.d/sentinel start 


4 Click Close. 


24.5.2 Monitoring the Health of Analytics Server Cluster 


The Health icon on the cluster row displays the status of the least healthy member of the cluster. For 
information about the meaning of health icons, see Section 24.1, “Health States,” on page 1099. 


To view details about the status of the cluster: 


1 Click Devices > Analytics Server. 
2 On the cluster row, click the Health icon. 
3 To ensure that the information is current, click Refresh. 


4 To view specific information about the status of Analytics Server, click the Health icon in the 
Analytics Server row. 
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25.1 


25.2 


Monitoring Alerts 


An alert is generated whenever the system detects a condition that prevents it from performing 
normal system services. Access Manager components have been programmed to issue alerts to 
various types of systems (such as a Novell Audit server, a Sentinel server, or a Syslog server) so that 
the administrator can be informed when significant changes occur that modify Access Manager 
performance. Alerts can also be configured so that the administrator is informed when significant 
changes occur. 


This section discusses the following topics: 


¢ Section 25.1, “Monitoring Identity Server Alerts,” on page 1109 
¢ Section 25.2, “Monitoring Access Gateway Alerts,” on page 1109 
¢ Section 25.3, “Monitoring Analytics Server Alerts,” on page 1114 


Monitoring Identity Server Alerts 


1 In Administration Console Dashboard, click Devices > Identity Servers > [Name of Server] > 
Alerts tab. 


2 To delete an alert from the list, select the check box for the alert, then click Acknowledge 
Alert(s). To remove all alerts from the list, click the Severity check box, then click Acknowledge 
Alert(s). 


3 Click Close. 


4 (Optional) To verify that the problem has been solved, click Identity Servers > [Name of Server] 
> Health > Update from Server. 


Monitoring Access Gateway Alerts 


This section discusses the following topics:. 


¢ Section 25.2.1, “Viewing Access Gateway Alerts,” on page 1110 

¢ Section 25.2.2, “Viewing Access Gateway Cluster Alerts,” on page 1110 
¢ Section 25.2.3, “Managing Access Gateway Alert Profiles,” on page 1110 
¢ Section 25.2.4, “Configuring an Alert Profile,” on page 1111 

¢ Section 25.2.5, “SNMP Profile,” on page 1112 

Ħ Section 25.2.6, “Configuring a Log Profile,” on page 1112 

¢ Section 25.2.7, “Configuring an E-Mail Profile,” on page 1113 

¢ Section 25.2.8, “Configuring a Syslog Profile,” on page 1113 
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25.2.1 Viewing Access Gateway Alerts 


1 In Administration Console Dashboard, click Devices > Access Gateways > [Name of Server] > 
Alerts. 


2 To delete an alert from the list, select the check box for the alert, then click Acknowledge 
Alert(s). To remove all alerts from the list, click the Severity check box, then click Acknowledge 
Alert(s). 


3 Click Close. 


4 (Optional) To verify that the problem has been solved, click Access Gateways > [Server Name] > 
Health > Update from Server. 


25.2.2 Viewing Access Gateway Cluster Alerts 


1 In Administration Console Dashboard, click Devices > Access Gateways > [Name of Cluster] > 
Alerts. 


2 Analyze the data displayed in the table. 


Column Description 


Server Name Lists the name of Access Gateway that sent the alert. To view additional 
information about the alerts for a specific Access Gateway, click the name 
of an Access Gateway. 


Severe Lists the number of critical alerts that have been sent and not 
acknowledged. 

Warning Lists the number of warning alerts that have been sent and not 
acknowledged. 

Information Lists the number of informational alerts that have been sent and not 
acknowledged. 


3 To acknowledge all alerts for an Access Gateway, select the check box for Access Gateway, 
then click Acknowledge Alert(s). When you acknowledge an alert, you clear the alert from the 
list. 


4 To view information about a particular alert, click the server name. 


25.2.3 Managing Access Gateway Alert Profiles 


For an Access Gateway, this option allows you to send notification of generated system alerts to 
Administration Console, to a Syslog server, to a log file, or to a list of e-mail recipients. 

1 In Administration Console Dashboard, click Devices > Access Gateways > Edit > Alerts. 

2 Select one of the following actions: 


New: To add a new profile, click New. Specify a name for the profile, then click OK. For 
configuration information, see Section 25.2.4, “Configuring an Alert Profile,” on page 1111. 


Enable: To enable a profile, select the check box next to the profile, then click Enable. 
Disable: To disable a profile, select the check box next to the profile, then click Disable. 
Delete: To delete a profile, select the check box next to the profile, then click Delete. 
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3 Click OK twice. 
4 On the Access Gateways page, click Update. 


25.2.4 Configuring an Alert Profile 


The alert profile determines which alerts are sent and where the alerts are sent. 

1 In Administration Console Dashboard, click Devices > Access Gateways > Edit > Alerts > 
[Name of Profile]. 

2 Select one or more of the following: 
Connection Refused: Generated when a connection is refused. 
Proxy Initialization Failure: Generated when the Embedded Service Provider fails to initialize. 
System Up: Generated each time Access Gateway is started. 
System Down: Generated each time Access Gateway is stopped. 


Configuration Changed: Generated each time the configuration of Access Gateway is 
modified. 


DNS Server Not Responding: (Access Gateway Appliance) Generated each time the DNS 
server stops responding. 


DNS Server Is Now Responding: (Access Gateway Appliance) Generated each time the DNS 
server comes up. 


DNS Parent Address Invalid: (Access Gateway Appliance) Generated when the IP address of 
DNS parent is invalid. 


DNS Resolver Initialization Failure (10 seconds): (Access Gateway Appliance) Generated 
when the DNS resolver initialization fails. 


DNS Resolver Initialization Failure (2 minutes): (Access Gateway Appliance) Generated 
when the DNS resolver initialization fails. 


Failure in Audit, Stopping Services: Generated when the audit server has failed, and Access 
Gateway has been configured to stop services. 


To configure Access Gateway to continue when auditing services are not available, click 
Auditing in dashboard, deselect the Stop Services on Audit Server Failure option, then click 
Apply. 

Failure in Audit, Will lose events, but continuing services: Generated when the audit agent 
has failed. Access Gateway continues to run, but no audit events are generated. 


As a workaround while solving this problem, you can enable proxy service logging (see 
Section 21.4.4, “Configuring Logging for a Proxy Service,” on page 1050). The common and 
extended log files provide some details on the HTTP traffic. 


If you do not want Access Gateway to run without generating events, you need to manually shut 
down Access Gateway. 


Failure in Audit, Server is offline: Generated when the audit agent is unable to contact the 
audit server. When this condition occurs, the audit agent uses local caching for the audit events. 


Do not allow this condition to continue indefinitely. Access Gateway soon reaches the limits of its 
local cache. If this happens, events can be lost and Access Gateway might need to stop 
services. 


For troubleshooting information, see “Troubleshooting Novell Audit” (http://www.novell.com/ 
documentation/novellaudit20/novellaudit20/data/al0In30.html) in the Novell Audit Administration 
Guide (http:/Awww.novell.com/documentation/novellaudit20/novellaudit20/data/bookinfo.html). 


3 Select where you want the alerts sent: 
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Send to Device Manager: Select this option to send alerts to Administration Console. 


Send to SNMP: (Access Gateway Service) Select this option to send alerts to an SNMP server. 
To configure the SNMP server, click the Send to SNMP link. For configuration information, see 
“SNMP Profile” on page 1112. 


Send to Log File: Select this option to send alerts to a log file. To send alerts to a log file, click 
New, specify a name for the log profile, then click OK. For configuration information, see 
“Configuring a Log Profile” on page 1112. 


To enable a log profile, select the profile, then click Enable. 
To disable a log profile, select the profile, then click Disable. 


To delete a log profile, select the profile, then click Delete. Click OK in the confirmation dialog 
box. 


Send E-mail Notifications: Select this option to send alerts through e-mail notifications. To 
enable e-mail notification click New, specify a name for the e-mail profile, then click OK. For 
configuration information, see “Configuring an E-Mail Profile” on page 1113. 


To enable an e-mail profile, select the profile, then click Enable. 
To disable an e-mail profile, select the profile, then click Disable. 


To delete an e-mail profile, select the profile, then click Delete. Click OK in the confirmation 
dialog box. 


Send to Syslog: Select this option to enable Syslog alerts. Click New, specify a name for the 
Syslog profile, then click OK. For configuration information, see “Configuring a Syslog Profile” on 
page 1113. 


To enable a syslog profile, select the profile, then click Enable. 
To disable a syslog profile, select the profile, then click Disable. 


To delete a syslog profile, select the profile, then click Delete. Click OK in the confirmation dialog 
box. 


4 To enable an alert action profile, select the action profile, click Enable, then click OK. 


The action to send the alerts to a log file, to e-mail addresses, or to a syslog file is not performed 
until the action profile is enabled. 


5 On the Alert Profiles page, verify that the alert profile you have created is enabled, then click OK 
twice. 


6 Update Access Gateway. 


25.2.5 SNMP Profile 


1 (Access Gateway Service) To add the IP address of a SNMP server, click New, specify the IP 
addresses, then click OK. 


2 (Optional) To delete an IP address, select the IP address, then click Delete > OK. 
3 Select one of the following: 

+ Add another profile, continue with Step 3 on page 1111. 

¢ Save your modifications, continue with Step 4 on page 1112. 


25.2.6 Configuring a Log Profile 


The Send to Log File field displays the name of the log profile you are configuring. 


1 Fill in the following fields: 
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Log File Name: Specify a name for the log file and a path where the file should be stored. 
You must specify the full path. 

+ Access Gateway Appliance/Service (Linux): /var/opt/novell/amlogging/logs/ 

+ Access Gateway Service (Windows): \Program Files\Novell\amlogging\logs\ 


Max File Size: Specify a maximum size for the log file in KB. The size can be from 50 to 100000 
KB. Specify 0 to indicate that there is no maximum file size. 


2 Click OK. 
3 Select one of the following: 
+ To add another profile, continue with Step 3 on page 1111. 
+ To save your modifications, continue with Step 4 on page 1112. 


25.2.7 Configuring an E-Mail Profile 


The Send E-Mail Notifications field displays the name of the e-mail profile you are configuring. 


1 Fill in the following fields: 


E-mail Recipients: To add a recipient to the list, click New, specify the e-mail address of the 
recipient, then click OK. You can add multiple e-mail addresses. To delete a recipient, select the 
user’s email address, click Delete, then click OK. 


Mail Exchange Servers: To add a mail server, click New, specify the IP address or the DNS 
name of the mail exchange server, then click OK. You can add multiple mail exchange servers. 
To delete a server, select the server, click Delete, then click OK. 


2 Click OK. 
3 Select one of the following: 
+ To add another profile, continue with Step 3 on page 1111. 
+ To save your modifications, continue with Step 4 on page 1112. 


25.2.8 Configuring a Syslog Profile 


The Send to Syslog field displays the name of the Syslog profile you are configuring. 


1 Fill in the following field: 


Facility Name: Specify a facility name for the Syslog server. It can be any name from local0 to 
local7. If you specify localO - local7 as your facility name, the alerts are stored at /var/log/ 
localmessages. 


2 Click OK. 
3 Select one of the following: 
+ To add another profile, continue with Step 3 on page 1111. 
+ To save your modifications, continue with Step 4 on page 1112. 
To configure the Syslog profile for Access Gateway Service on RedHat Enterprise Linux, use the 
following procedure: 
1 Go to /etc/rsyslog.conf file. 
2 Add the following under # Provides UDP syslog reception 
$ModLoad imudp.so 
$UDPServerRun 514 
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3 Restart the syslog service using one of the following commands: 
/etc/init.d/rsyslog restart OR rcsyslog start 


25.3 Monitoring Analytics Server Alerts 


This section discusses the following topics:. 


¢ Section 25.3.1, “Viewing Analytics Server Alerts,” on page 1114 
¢ Section 25.3.2, “Viewing Analytics Server Cluster Alerts,” on page 1114 


25.3.1 Viewing Analytics Server Alerts 


1 In Administration Console Dashboard, click Devices > Analytics Server > [Name of Server] > 
Alerts. 


2 To delete an alert from the list, select the check box for the alert, then click Acknowledge 
Alert(s). To remove all alerts from the list, click the Severity check box, then click Acknowledge 
Alert(s). 


3 Click Close. 


4 (Optional) To verify that the problem has been solved, click Access Gateways > [Server Name] > 
Health > Update from Server. 


25.3.2 Viewing Analytics Server Cluster Alerts 


1 In Administration Console Dashboard, click Devices > Analytics Server > [Name of Cluster] > 
Alerts. 


2 Analyze the data displayed in the table. 


Column Description 
Server Name Lists the name of the Analytics Server that sent the alert. To view additional 


information about the alerts for a specific Analytics Server, click the name 
of an Analytics Server. 


Severe Lists the number of critical alerts that have been sent and not 
acknowledged. 

Warning Lists the number of warning alerts that have been sent and not 
acknowledged. 

Information Lists the number of informational alerts that have been sent and not 
acknowledged. 


3 To acknowledge all alerts for an Analytics Server, select the check box for the Analytics Server, 
then click Acknowledge Alert(s). When you acknowledge an alert, you clear the alert from the 
list. 


4 To view information about a particular alert, click the server name. 


1114 Monitoring Alerts 


26.1 


Monitoring Access Manager By Using 
Simple Network Management Protocol 


Administration Console captures all statistics sent by Identity Server and Access Gateway. These 
statistics sent at periodic intervals, are stored in eDirectory. 


You can use any Network Monitoring System (NMS) or an SNMP-enabled client to gather statistics 
from Administration Console by using Simple Network Management Protocol (SNMP). Simple 
Network Management Protocol (SNMP) is a network management protocol for network management 
that collects information from devices on a network. Access Manager supports SNMP v2 for the 
purpose of monitoring Identity Server and Access Gateway. 


NOTE: This release of Access Manager does not support SNMP traps. 


SNMP Architecture in Access Manager 


Access Manager introduces Master Agent, Sub Agent, and a Management Information base (MIB) 
file to work with any third-party monitoring software using SNMP. 


The Master Agent runs as a service in Administration Console and listens to the Sub Agents 
registered with it. A Sub Agent is a managed device that is registered with the Master Agent and 
exchanges information with it using TCP port 705. The MIB file contains a hierarchical list of variables 
and defines the information that is provided by the devices. Each variable in this list is uniquely 
identified by an OID (Object Identifier) and are read-only in nature. 


Administration Console contains both Master Agent and Sub Agent. Master Agent runs as a separate 
service and the Sub Agents are registered with the Master Agent for monitoring. Administration 
Console gathers statistics from all devices and acts as a centralized repository for any monitoring tool 
to access the data by using SNMP. The external NMS contacts Administration Console to get the data 
about any Identity Server or Access Gateway by using SNMP. For this communication it uses UDP 
port 161 (by default). 


In a clustered Administration Console setup, the devices send statistics to the secondary 
Administration Console in case the primary Administration Console is down. 
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Figure 26-1 Architecture of SNMP Components in Access Manager 
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This MIB file contains all Identity Server and Access Gateway attributes available to monitor the state 
of the system. Figure 26-1 on page 1116 illustrates how Administration Console uses SNMP to 
monitor Identity Server and Access Gateway. 


If you are installing or upgrading Access Manager on a Linux server, the Master Agent is 
automatically installed. A Windows server has an in-built SNMP Master Agent, but it does not support 
the AgentX protocol. The AgentX protocol is used for communication between the Master Agent and 
Sub Agent. Due to this, if you are installing Access Manager on a Windows server, the Master Agent 
has to be downloaded and installed manually. For more information about installing the Master Agent 
on a Windows server, see Section 26.5.2, “Installing and Enabling Monitoring for Access Manager on 
Windows,” on page 1120 


26.2 Features of Monitoring in Access Manager 


In Access Manager 4.0, monitoring using SNMP includes the following features: 


¢ Ability to enable/disable monitoring - By default SNMP is not enabled. You can configure it to 
enable monitoring for Access Manager components. For details about enabling monitoring, see 
“Installing and Enabling Monitoring for Access Manager Components” on page 1119 


¢ Facility to change port information or IP address of the Master Agent- You can configure the 
Master Agent to listen on a different port or IP address. The default port is TCP 705. 


+ Master Agent and Sub Agent architecture support multiple sub agents - The Master Agent - Sub 
Agent architecture helps you configure additional Sub Agents to be monitored. For example, you 
can configure a single Master Agent to receive data from Access Manager components, 
eDirectory as well as SLES Sub-Agents. 


e Automatic data synchronization on device addition or removal - The MIB structure is 
automatically adjusted for dynamic addition or removal of components 


+ Automatic reconnect to Master Agent - Every time Administration Console is restarted the 
reconnection to the MasterAgent happens automatically. No manual steps are required. 
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26.3 Using the Default MIB File with External SNMP 
Systems 


When Access Manager is installed, NAM. mib file is placed in the opt /novell/devman/share/conf 
folder. On a Windows server this file is placed in the C:\Program Files 
(x86) \Novell\Tomcat \webapps\roma\WEB- INF\ folder. 


This MIB file contains textual information of Identity Server and Access Gateway attributes. You can 
use these attributes to monitor the state of the system. The attributes are uniquely identified by an 
OID (Object Identifier) or namespace. Figure 26-2 on page 1117 shows the hierarchy of a MIB file 
when viewed with a MIB browser. 


Figure 26-2 The MIB file viewed in a MIB Browser 


iso.org.dod.internet.private.enterprises. 
.1.3.6.1.4.1. 


netigq.mibdoc.namMIB.namStatistics. 
.1.3.6.1.4.1.1691.2.100.1. 


namComponents.namDevices. 


-1.3.6.1.4.1.1691.2.100.1.1.1 


identityProvider. accessGateway. 
.1,3.6.1.4.1.1691.2.100.1.1.1.1 .1,3.6.1.4.1.1691.2.100.1.1.1.2 


idpAuthentication. T agServerActivity. 
.1.3.6.1.4.1.1691.2.100.1.1.1.1.2 .1.3.6.1.4.1.1691.2.100.1.1.1.2.1 


idpAuthenticationProvided. F- agCpuUtilization. Jl- 
E2 


.1.3.6.1.4.1.1691.2.100.1 .1.3.6.1.4.1.1691.2.100.1.1.1.2.1.1 


Each statistic entry in the MIB file has a corresponding description to help identify the attribute. 
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Figure 26-3 Description of an attribute in the MIB file 


=} jy mibdoc 
S-i namMB 
=} }) namStatistics 
=|. }) namComponents 
=}. |) namDevices 
=|; }) identityProvider 


=}; }) idpApplication 
F 
= idpMemoryEntry 
~~ idpMemoryDevicelp 


~~ idpMemory 
-@ idpMemoryindex 
-do idpAuthentication 
H- idpIncomingRequests 
Hdb idpOutgoingRequests 
Name | idpMemoryTable 
OID -1.3.6.1.4.1.1691.2.100.1.1.1.1.1.1 
MIB | NETIQ-ACCESSMANAGER-MIB 


Syntax SEQUENCE OF IdpMemoryEntry 
Access not-accessible 


Status current 

DefVal 

Indexes _| idpMemoryIndex 
Descr Memory of the device 


Every time a new Identity Server or Access Gateway is added or removed the SNMP data available 
in Administration Console is updated. If a device is not accessible for some reason, the MIB file 
(when viewed with a MIB Browser) displays the last reported statistics for all the attributes except for 
the Health Status of the devices. The Health Status of the devices are updated periodically. 


26.4 Querying For SNMP Attributes 


To query any SNMP attribute the following details are needed: 


+ IP Address of Administration Console 

+ The community string name 

¢ The Object Identifier (OID) of the attributelD 

+ The IP address of the device - Identity Server or Access Gateway. 


For example, consider a scenario where you want to query the memory utilization of an Identity 
Server with IP address 10.0.0.0. The query is issued to Administration Console whose IP address is 
192.168.0.0 


You can perform the query either by using the OID or by using the namespace of the object. 
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26.4.1 


26.4.2 


26.4.2.1 


26.5 


If you are using the net-snmp package for monitoring, the equivalent command to retrieve memory 
utilization details are: 


Querying Using the Namespace 


snmpget -v2c -m /opt/volera/roma/conf/NAM.mib -c netiq 192.168.0.0 
.iso.org.dod.internet.private.enterprises.netiq 
.mibdoc.namMIB.namStatistics.namComponents.namDevices.identityProvider .idpApplicat 
ion.idpMemoryTable.idpMemoryEntry.idpMemory.10.0.0.0 


NOTE: You must provide the exact path of the Access Manager mib file. 


Querying Using the OID 
snmpget -v2c -c netig 192.168.0.0 .1.3.6.1.4.1.1691.2.100.1.1.1.1.1.1.1.1.10.0.0.0 


In the same manner, you can query values of various attributes supported by Identity Server and 
Access Gateway. 


Using the same example, if you query idpHealthEntry parameter by using the Namespace, the 
command is: 


snmpget -v2c -m /opt/volera/roma/conf/NAM.mib -c netiq 192.168.0.0 
.iso.org.dod.internet.private.enterprises.netiq.mibdoc.namMIB.namStatistics.namCom 
ponents.namDevices.identityProvider .idpApplication.idpMemoryTable.idpMemoryEntry.i 
dpMemory.10.0.0.0 


The idpApplication parameter is substituted with the idpHealthEntry attribute in the above example. 


NOTE: You must provide the exact path of the Access Manager mib file. 


Understanding Return Values of an SNMP Query 


When an SNMP query is performed, it retrieves the last fetched data from Administration Console. If 
the device is down or not reachable a negative value is retrieved. 


For example: If you query for the idpHealthyEntry attribute, the value that is returned can be Red, 
Yellow, Green or NoReport. 


NOTE: The return value of NoReport indicates a server that is disconnected or unavailable. 


Installing and Enabling Monitoring for Access 
Manager Components 


¢ Section 26.5.1, “Installing and Enabling Monitoring for Access Manager on Linux,” on page 1120 


¢ Section 26.5.2, “Installing and Enabling Monitoring for Access Manager on Windows,” on 
page 1120 
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26.5.1 Installing and Enabling Monitoring for Access Manager on 
Linux 


1 To install the Master Agent and Sub Agent on Linux, no manual steps are required. 


All packages necessary to monitor Access Manager are automatically installed during upgrade 
or installation. Administration Console is automatically installed and configured as the Master 
Agent and the Sub Agents are in turn registered with Administration Console for monitoring. 


2 In the opt/novell/devman/share/conf/platform.conf file, traverse to the vcdn module for 
SNMP. In <stringParam name="enable" value="false", replace false with true and save the 
file using :wq!. 


This enables monitoring between Access Manager devices. 


The vcdn module also contains port details. If needed, you can configure the Master Agent to 
listen on a different port or IP address. The default port is TCP 705. 


3 In the snmp-master-agent.conf file, change the community name. The default name is netigq. 
Changing the community name is recommended for security purpose. 


4 Start the Master Agent by using the /etc/init.d/novell-snmpd start command. 
If you want to start SNMP automatically after booting the server, perform the following steps: 
1. Start YaST. 
2. Navigate to System > System Services (Run Level) (On SLES 11 SP4). 
Or 
Navigate to System > Services Manager (On SLES 12 SP1). 
3. Traverse to novell-snmpd, then press F3 to enable SNMP. 


4. Restart Administration Console using /etc/init.d/novell-ac restart command for the 
changes to take effect. 


5 If you encounter any errors while enabling monitoring, review the platform.@.1og file available 
in the /var/opt/novell/nam/logs/adminconsole/volera folder. 


26.5.2 Installing and Enabling Monitoring for Access Manager on 
Windows 


1 Ona Windows server, the Master Agent has to be manually installed and configured. 


Download the latest net -snmp package and install it. For downloading binaries, go to 
Sourceforge (The supported version is 5.6.1.1). 


2 Register windows service by running the following command: 


C:\usr\bin\snmpd.exe -register -Lf "C:/usr/log/snmpd.log" -c "C:/Program Files 
(x86) /Novell/Tomcat/webapps/roma/WEB- INF/conf/snmp-master -agent.conf" 


If you uninstall net-snmp, it is important to unregister. Use the following command to unregister: 


C:\usr\bin\snmpd.exe -unregister -Lf "C:/usr/log/snmpd.log" -c "C:/Program 
Files(x86)/Novell/Tomcat/webapps/roma/WEB-INF/conf/snmp-master -agent.conf" 


3 Inthe C:\Program Files (x86\Novell\Tomcat \webapps\roma\WEB- 
INF\conf\platform.conf file, traverse to the vcdn module. 


In<stringParam name="enable" value="false", replace false with true. This enables 
monitoring between Access Manager devices. 


The vcdn module also contains port details. If needed, you can configure the Master Agent to 
listen on a different port or IP address. The default port is TCP 705. 
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In the snmp-master -agent .conf file, change the community name. The default name is netig. 


Changing the community name is recommended for security purpose. 
Start the Master Agent by using the net start "Net-SNMP Agent" command. 


NOTE: Ensure that you specify the command within quotes to start the Master Agent. 


Restart Administration Console for the changes to take effect. 


7 If you encounter any errors while enabling monitoring, review the logs available in the 


C:\Program Files (x86)\Novell\log\platform.@.1og folder. 


If you are on a Windows server, then enabling SNMP monitoring does not update the 
platform.0.1og file. 


To enable SNMP Monitoring and ensure platform.0.1og file is updated, perform the following 


steps: 
7a Stop Tomcat server. 


7b Edit the C:\Program Files (x86)\Novell\Tomcat \webapps\roma\WEB- 
INF\conf\platform.conf file. 


7c Traverse to the end of the platform.conf file and locate the last </vcdnModule> tag. 


7d Add the following content to appear after the last </vcdnModule> tag 


<vcdnModule name="snmp" 
className="com.volera.vcdn.platform.snmp.SnmpAgentInit" 
sequence="3"> 

<stringParam name="enable" value="true"/> 


<stringParam name="masterAgentIp" value="127.0.0.1"/> 


<stringParam name="masterAgentPort" value="705"/> 
</vcdnModule>. 


Ensure that this content is placed inside the <vcdnApplicationModule> tag. 
7e Start the Tomcat server. 


This ensures that SNMP Monitoring is enabled on a Windows server and the plat form. log 


file is also updated. 
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2 [ Impersonation 


27.1 


27.2 


Impersonation enables a help desk user to perform certain actions on behalf of users without knowing 
their credentials. The help desk user can login on behalf of the user and troubleshoot an issue. This 
helps the help desk user gain access to the user’s existing configuration and perform the necessary 
actions required for troubleshooting. 


With the help of audit events, the user can view the impersonated logs. This will also help determine 
the details of the impersonator and impersonatee along with the session details. 


Example: Let’s suppose Alice encounters an issue and is unable to access a target application. She 
reaches out to the help desk user seeking for help. Joe, from the help desk, logs in to Access 
Manager with his credentials and sends a request to Alice to access her system. When Alice receives 
the request from Joe, she grants permission. Joe initiates an impersonated session and 
troubleshoots the issue. 

¢ Section 27.1, “Impersonation Terminology,” on page 1123 

¢ Section 27.2, “Prerequisites,” on page 1123 

¢ Section 27.3, “Enabling Impersonation,” on page 1124 

¢ Section 27.4, “Impersonation Flow,” on page 1124 

¢ Section 27.5, “Implementing Impersonation in Custom Portal Pages,” on page 1125 

¢ Section 27.6, “Audit Event for Impersonation,” on page 1127 

¢ Section 27.7, “Troubleshooting,” on page 1127 


Impersonation Terminology 


The following list includes frequently used terms in an Impersonation flow: 


+ Impersonator: A help desk user authorized to perform impersonation on a user’s setup. 
+ Impersonatee: A user whose identity is being impersonated by the help desk user. 


+ impersonated Session: A user session created for an impersonator to perform impersonation. 


Prerequisites 


The following are prerequisites for creating an impersonated session: 


¢ Before initiating an impersonated session, the administrator must create a policy for the session. 
This policy must be created under Impersonation administrator’s interface. To create a policy, 
see Section 8.2, “Role Policies,” on page 721. 


Example: Let’s suppose a user belongs to the group membership, Access Helpdesk, and 
creates a role called Access Impersonator. Now create another group of users with role Access 
Impersonatee and map it to Access Impersonator role. Now, only Access Impersonator can 
impersonate Access Impersonatee role users. 
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27.3 


27.4 


To initiate impersonation, the Access Impersonator requests impersonation from the Access 
Impersonatee. Upon approval, the Access Impersonatee clicks the Help Desk Session and is 
notified that the Impersonation is in progress. 


+ The Impersonator must have the role that is authorized to perform Impersonation. 
+ The Impersonatee has to give consent to the impersonator to access the session. 


Enabling Impersonation 


To enable impersonation, perform the following tasks: 


NOTE: Impersonation is only possible on an active user session. If two help desk users initiate an 
impersonation session for the same end user simultaneously, only the latest request is considered. 


1 In Administration Console Dashboard, click Impersonation. 

2 Select a cluster from the list. 

3 Select Enable impersonation. 

4 Under Role Groups, select a Help Desk Role and the corresponding Roles to Impersonate. 


Impersonation Flow 


Before initiating the work flow, ensure that Impersonation is enabled. To enable Impersonation, see 
Section 27.3, “Enabling Impersonation,” on page 1124. 


Perform the following tasks to complete an Impersonated session: 
Impersonator Tasks: 


1 Log in to Access Manager as an impersonator. 


2 In the user portal page, click <user name> at the top right of the page and then click Start Help 
Desk Session. 


3 Specify the user name and ask for permission. 


NOTE: Only an impersonator can terminate an active impersonated session. 


Impersonatee Tasks: 


1 Log in to Access Manager as an impersonatee. 


2 In the user portal page, click <user name> at the top right of the page and then click Help Desk 
Session. 


3 Approve or Deny the request from impersonator. The impersonator receives the request. 


Upon receiving an approval from the impersonatee, the impersonated session is successfully 
initiated. 
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27.5 


27.5.1 


Implementing Impersonation in Custom Portal 
Pages 


This section describes how to customize your custom portal pages for Impersonation. To determine if 
you have customized Identity Server, see Section 4.1.3, “Customizing Identity Server,” on page 254. 


To implement the customization in your customized Identity Server, you must understand which files 
to modify and when to display the modified files. 


¢ Section 27.5.1, “Understanding the Specific JSP Files,” on page 1125 
¢ Section 27.5.2, “Determining when to Show the Specific JSP Files,” on page 1126 


Understanding the Specific JSP Files 


Access Manager uses two . jsp files that control how Impersonation functions. You can load these 
files as stand-alone web pages, or into an iFrame on an existing web page. The files are defined in 
the following table: 


Table 27-1 Impersonation JSP Files 


File name Location Description 
impersonator.jsp https://NIDP-hostname:port/ The impersonator. jsp file controls all 
nidp/jsp/impersonator.jsp impersonator actions, including sending a help 


desk session request to the impersonatee, 
seeing the status of a help desk session 
request that has already been sent, canceling a 
help desk session request, and ending a 
current help desk session. 


impersonatee.jsp https://NIDP-hostname:port/ The imperonatee. jsp controls all 
nidp/jsp/impersonatee.jsp impersonatee actions, including seeing a help 
session request from the impersonator, 
approving or denying the request, and seeing 
whether a previously approved request is 
active or has ended. 


If you have built a custom user portal for your users, there is an additional file you must edit. The file 
is located on Identity Server at /opt/novell/nids/lib/webapp/jsp/impersonator.jsp. You need 
to make a change to the default login page (line 218): 


window.parent.location = "/nidp/portal"; 


You must make a different change depending on if the custom user portal loads as an iFrame ora 
stand-alone web page. 


iFrame: You must change "/nidp/portal" to be the full URL of the page that loads when an active 
impersonation session starts. For example: 


window.parent.local="URL of the page that loads after an active impersonation 
session starts" 


Stand-alone web page: You must also change the line to: 


window.location="URL of the page that loads after an active impersonation session 
starts" 
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27.5.2 Determining when to Show the Specific JSP Files 


You must build logic into your custom web pages of when to show the impersonator .jsp file or the 
impersonatee. jsp file for a specific authenticated session. Also, use the following information to 
build the menu options in the web pages for impersonation. 


There is an endpoint in Identity Server that the default User Portal uses to determine which 
impersonation-related menu items to display for a particular end-user session. The endpoint is 
located at: https: //NIDP-hostname: port/nidp/portal/uilcons. xml 


When you send an HTTP GET request to that endpoint from an authenticated session, it returns XML 
similar to the following: 


<UIIcons> 

<UIIcon altText="Help Desk Session..." linkTarget="_top" 
tags="LANDING_PAGE |width=425 | type=dialog|height=300" title="Help Desk Session..." 
url="nidp/jsp/impersonatee.jsp"/> 


<UIIcon altText="Start Help Desk Session..." linkTarget="_top" 
tags="LANDING_PAGE | width=425 | type=dialog|height=300" title="Start Help Desk 
Session..." url="nidp/jsp/impersonator.jsp"/> 

</UIIcons> 


Within the UIIcons element, there are zero, one, or two child elements named UIIcon. The title 
attribute on those elements is one of the following three strings (if the user's locale indicates English): 


End Help Desk Session 


+ When this element is available, the default User Portal displays a menu item with the same 
name. When a user selects this menu item, it ends impersonation by calling https: //NIDP- 
hostname: port/nidp/app/ilogout. 


NOTE: The impersonator. jsp file also includes a way to end a current impersonation session, 
so you do not need to check or act on this particular element if you have implemented this in the 
impersonator. jsp file. 


¢ This element is available only if the Impersonation feature is enabled in Administration Console, 
and only if the currently authenticated session is an active impersonation session. 


+ When this element is available, the other two elements: Start Help Desk Session and Help Desk 
Session are not available. 
Start Help Desk Session 


+ When this element is available, the default User Portal displays a menu item with the same 
name. When a user selects this menu item, the User Portal loads impersonator.jsp in an 
iFrame. 


¢ This element is only available if the Impersonation feature is enabled in Administration Console, 
the currently authenticated session is not an active impersonation session, and the currently 
authenticated user has a help desk role (as configured in the Impersonation feature configured in 
Administration Console). 


+ When this element is available, the Help Desk Session element is also available. 
Help Desk Session 


+ When this element is available, the default User Portal displays a menu item with the same 
name. When a user selects this menu item, the User Portal loads the impersonatee. jsp file in 
an iFrame. 
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¢ This element is available only if the Impersonation feature is enabled in Administration Console, 
and the currently authenticated session is not an active impersonation session. 


+ When this element is available, the Start Help Desk Session element might also be available, if 
the currently authenticated user has a help desk role (as configured in the Impersonation feature 
configuration in Administration Console). 


27.6 Audit Event for Impersonation 


To view the list of audit events, see Section 30.17, “Access Manager Audit Events and Data,” on 
page 1292. 


27.7 Troubleshooting 


For troubleshooting information, see Section 30.14, “Troubleshooting Impersonation,” on page 1267. 
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Back Up and Restore 


You can run backup and restore utilities from the command line to back up and restore your Access 
Manager configuration. An additional script, Diagnostic Configuration Export, allows you to export 
your configuration so NetIQ Support can help diagnose possible configuration problems. 


For more information about the Diagnostic Configuration Export utility, see Section 30.1.2, 
“Diagnostic Configuration Export Utility,” on page 1153. 


The following sections describe how to back up and restore your Access Manager configuration, how 
to export your configuration for NetIQ Support, and how to restore the configuration of Identity 
Servers and Access Gateways: 

¢ Section 28.1, “How The Backup and Restore Process Works,” on page 1129 

¢ Section 28.2, “Backing Up the Access Manager Configuration,” on page 1130 

¢ Section 28.3, “Restoring the Access Manager Configuration,” on page 1131 

¢ Section 28.4, “Restoring an Identity Server,” on page 1134 

¢ Section 28.5, “Restoring an Access Gateway,” on page 1135 


28.1 How The Backup and Restore Process Works 


¢ Section 28.1.1, “Default Parameters,” on page 1129 
¢ Section 28.1.2, “The Process,” on page 1129 


28.1.1 Default Parameters 


Linux: All scripts call the getparams.sh script to request the parameters from users. The 
defbkparm.sh script is created by the Access Manager installation. It contains the default parameters 
for different options required by the underlying backup and restore utilities. If the entries in this file are 
commented out, the user is prompted for additional parameters. 


Windows: The default parameters are specified in the defbkparm. properties file. It contains the 
default parameters for different options required by the underlying backup and restore utilities. If the 
entries in this file are commented out, the user is prompted for additional parameters. 


28.1.2 The Process 


The backup script must be run on the primary Administration Console. It creates a ZIP file that 
contains all certificates that various devices use and an encrypted LDIF file that contains 
configuration parameters for all imported devices. You do not need to back up the configuration of 
individual devices. By backing up the primary Administration Console, you back up the configuration 
of all Access Manager devices. 


The backup script backs up objects in the ou=accessManagerContainer.o=novell container. It does 
not back up the following: 


+ Admin user account and password 
¢ Delegated administrator accounts, their passwords, or rights 
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+ Policy View user accounts, their passwords, or rights 

+ Role Based Services (RBS) configuration 

¢ Modified configuration files on the devices such as the web. xm1 file 
¢ Local files installed on devices such as log files 

+ Custom login pages, custom error pages, or custom messages 


You need to perform you own backup of custom or modified configuration files. 


For information on how to perform a configuration backup, see Section 28.2, “Backing Up the Access 
Manager Configuration,” on page 1130. 


You need to restore a backup when Administration Console fails. If another device fails, you simply 
replace the hardware, reinstall the device using the IP address of the failed device, and the device 
imports into Administration Console and acquires the configuration of the failed device. 


For the details of this process, see Section 28.4, “Restoring an Identity Server,” on page 1134 and 
Section 28.5, “Restoring an Access Gateway,” on page 1135. 


If Administration Console fails, you need to restore the configurations you backed up. Replace the 
hardware and reinstall Administration Console by using the DNS name and IP address of the failed 
console. Then use the restore utility to restore the certificates and the device configuration. 
Administration Console notifies all devices that it is online and they resume communicating with it 
rather than using a secondary console. 


For details of this process, see Section 28.3.1, “Restoring the Configuration on a Standalone 
Administration Console,” on page 1132. 


If Identity Server was installed with Administration Console, the backup file contains only the Tomcat 
configuration details for Administration Console. After you have installed Administration Console and 
restored the configuration, you need to install Identity Server. Identity Server will acquire its 
configuration parameters from Administration Console. For details of this process, see 

Section 28.3.2, “Restoring the Configuration with an Identity Server on the Same Machine,” on 

page 1133. 


28.2 Backing Up the Access Manager Configuration 


1 On the primary Administration Console, change to the utility directory. 
Linux: /opt/novell/devman/bin 
Windows Server 2012: \Program Files (x86)\Novell\bin 
2 Run the following command: 
Linux: ./ambkup.sh 
Windows: ambkup. bat 
Specify and confirm the Access Manager administration password. 
Specify a path to save the backup files. 
(Windows) Specify the name for the ZIP file. 
Specify a password for encrypting and decrypting private keys, then re-specify it for verification. 


on fF Ww 


You must use the same password for both backup and restore. 
7 Press Enter. 
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28.3 


NOTE: After running the backup script, check the logs to verify that no errors occurred while running 
the backup script. The log file location is displayed at the end of the script execution. 


The backup script creates a ZIP file containing several files including the certificate information. This 
file contains the following: 

¢ The configurations store’s CA key. 

+ The certificates contained in the configuration store. 

¢ The trusted roots in the trustedRoots container of the accessManagerContainer object. 


+ An encrypted LDIF file, containing everything found in the 
OU=accessManagerContainer,O=novell container. 


+ Aserver.xml file containing the Tomcat configuration information for Administration Console. 

+ A“delegatedusers_list” file containing the details of delegated users. 

+ A“policyviewusers_list” file containing the details of delegated users. 

+ A“backup_info” file that contains the basic details of the system on which the backup is being 
taken. 


The trusted roots are backed up in both LDIF and ZIP files. They are added to the ZIP file so that the 
ZIP file has the complete certificate-related configuration. 


IMPORTANT: The backup utility prompts you for a location to store the backup file. Select a location 
from where the backup file will not be deleted when you uninstall the product. The default location for 
Linux is /root/nambkup and for Windows it is C: /nambkup. 


Name of the backup zip file stores some information. Do not change the name. 


NOTE: Whenever the configuration store contains a Key Material Object (KMO) with a certificate 
signing request in pending state, the KMO will not be exported by using the amdiagcfg script and not 
be backed up by using the ambkup script. 


NOTE: For security purposes, delegated users, policy view users, and users in the trusted and 
configuration stores are not backed up. You need to recreate them while restoring the configuration. 
You can find the common name and full name of these users during the restore process or in the files 
in the zip file. 


Restoring the Access Manager Configuration 


The restore script replaces the existing configurations in the configuration database with the 
configuration in the backup of the configuration store. It should be used to restore configuration data 
in one of the following scenarios: 


+ An upgrade failed and you need to return to the configuration before the upgrade. 


e You want to return to the backed up configuration because the current modified configuration 
does not meet your needs. 


If the primary Administration Console machine has failed, you have lost both the configuration and 
the configuration database. To recover from this scenario, you need to do more than restore the 
configuration. 
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For instructions, see Section 30.1.6, “Moving the Primary Administration Console to New Hardware,’ 
on page 1155. 


The restore script cannot be used to move Administration Console to a different platform, even if the 
new machine is configured to use the same IP address and DNS name. The backup files contains 
path information that is specific to the operating system. You can convert a secondary Administration 
Console to a primary Administration Console. For more information, see Section 30.1.7, “Converting 
a Secondary Administration Console into a Primary Console,” on page 1156. 


The restoration steps are dependent upon whether Administration Console is installed on its own 
machine or with other Access Manager components: 


¢ Section 28.3.1, “Restoring the Configuration on a Standalone Administration Console,” on 
page 1132 


¢ Section 28.3.2, “Restoring the Configuration with an Identity Server on the Same Machine,” on 
page 1133 


NOTE: Restore should be made on the same version that was used to take the backup. 


28.3.1 Restoring the Configuration on a Standalone 
Administration Console 


1 Ensure that the .zip file created during the backup process is accessible. 
2 Log in as root. 
3 Change to the utility directory. 
Linux: /opt/novell/devman/bin 
Windows Server 2012: \Program Files (x86)\Novell\bin 
4 Run the following command: 
Linux: ./amrestore.sh 
Windows: amrestore. bat 
Specify and confirm the Access Manager administration password. 
Specify the path where the backup file is stored. 
Specify the name of the backup file. Do not include the .zip extension. 


oN O UO 


Specify the private key encryption password, then press Enter. 
Confirm the private key encryption password, then press Enter. 


9 (Conditional) If you have modified the Tomcat password or any other configuration on the Linux 
machine: 


9a Modify the server.xml file with changes that you have made in the Tomcat directory. 
/opt/novell/nam/adminconsole/conf 
9b Restart Tomcat by running the following command: 
/etc/init.d/novell-ac restart OR rcnovell-ac restart 
10 (Windows) Reboot the machine. 
11 If you have a secondary Administration Console installed, reboot the machines. 
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28.3.2 


28.3.2.1 


12 If any devices report certificate errors, you need to re-push the certificates. 
12a Click Troubleshooting > Certificates. 
12b Select the store that is reporting errors, then click Re-push certificates. 
You can select multiple stores at the same time. 
12c (Optional) To verify that the re-push of the certificates was successful, click Security > 
Command Status. 


If you are restoring only Administration Console, other components should still function properly after 
the restore. 


Restoring the Configuration with an Identity Server on the 
Same Machine 


Select the type of machine Administration Console is installed on: 


¢ Section 28.3.2.1, “Linux,” on page 1133 
¢ Section 28.3.2.2, “Windows,” on page 1134 


Linux 


Whenever you run the amrestore.sh script, Administration Console is restored as a standalone 
Administration Console. You must perform the steps described in Step 8 to restore your Identity 
Server into the configuration. 

Ensure that the .zip file created during the backup process is accessible. 

Log in as root. 

Change to the /opt/novell/devman/bin directory. 


A WN RF 


Run the following command: 


./amrestore.sh 


ol 


Specify the Access Manager administration user ID and password. 
6 Specify the name of the backup file. Do not include the .zip extension. 
7 Specify the private key encryption password, then press Enter. 
Confirm the private key encryption password, then press Enter. 
8 For Identity Server, complete the following steps after the restore process is completed: 


8a Remove Identity Server from the cluster configuration. See “Removing a Server from a 
Cluster Configuration” on page 74. 


8b Delete Identity Server from Administration Console. (See “Managing a Cluster of Identity 
Servers” on page 66.) 


8c Uninstall Identity Server. (See Uninstalling the Identity Server in the NetIQ Access Manager 
4.3 Installation and Upgrade Guide. 


This is required if Identity Server is installed on the machine. If you installed Identity Server 
before running the amrestore.sh script, you need to uninstall Identity Server. 


8d Install Identity Server. (See Installing the Identity Server on Windows in the NetIQ Access 
Manager 4.3 Installation and Upgrade Guide. 


8e If you have customized login pages, error pages, messages, or configuration files, copy 
these files to Identity Server. 
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8f Reassign Identity Server to the cluster configuration that it was removed from. (See 
“Assigning an Identity Server to a Cluster Configuration” on page 71”.) 


8g Update Identity Server. 
9 (Conditional) If any devices report certificate errors, you need to re-push the certificates. 
9a Click Troubleshooting > Certificates. 
9b Select the store that is reporting errors, then click Re-push certificates. 
You can select multiple stores at the same time. 


9c (Optional) To verify that the re-push of the certificates was successful, click Security > 
Command Status. 


28.3.2.2 Windows 


To perform a restore when an Administration Console and an Identity Server are installed on the 
same machine: 
1 Log in to as an administrator user. 
2 Run the Access Manager restore utility. 
2a From a command line, change to the utility directory: 
Windows Server 2012: \Program Files (x86)\Novell\bin directory. 
2b Specify amrestore. bat. 
2c Answer the prompts. 


3 Remove Identity Server from the cluster configuration. (See ““Removing a Server from a Cluster 
Configuration” on page 74”.) 


4 Delete Identity Server from Administration Console. (See ““Managing a Cluster of Identity 
Servers” on page 66”.) 


5 Install Identity Server on Administration Console. (See “Installing the Identity Server on Windows 
in the NetlQ Access Manager 4.3 Installation and Upgrade Guide”. 


6 If you have customized login pages, error pages, messages, or configuration files, copy these 
files to Identity Server. 


7 Reassign Identity Server to the cluster configuration that it was removed from. (See ““Assigning 
an Identity Server to a Cluster Configuration” on page 71”.) 


8 Update Identity Server. 


28.4 Restoring an Identity Server 


If any hardware failure occurs such as a failed hard disk on Identity Server machine, you can 
preserve its configuration and apply it to the replacement machine. 


1 Remove Identity Server from Identity Server cluster configuration. (See “Removing a Server 
from a Cluster Configuration” on page 74.) 


2 Delete Identity Server from Administration Console. (See “Managing a Cluster of Identity 
Servers” on page 66.) 


3 Uninstall Identity Server. (See Uninstalling the Identity Server in the NetIQ Access Manager 4.3 
Installation and Upgrade Guide. 


This is not required when you are using a new machine for the restored Identity Server. 


1134 Back Up and Restore 


28.5 


28.5.1 


4 Install the new Identity Server, which imports it into Administration Console. (See Installing the 
Identity Server on Windows in the NetIQ Access Manager 4.3 Installation and Upgrade Guide.) 


5 If you have customized login pages, error pages, messages, or configuration files, copy these 
files to Identity Server. 


6 Assign the new server to Identity Server cluster configuration. (See ““Assigning an Identity 
Server to a Cluster Configuration” on page 71”.) 


Restoring an Access Gateway 


If any hardware fails on Access Gateway machine, you can preserve its configuration and apply it to 
the replacement machine. 

¢ Section 28.5.1, “Clustered Access Gateway,” on page 1135 

¢ Section 28.5.2, “Single Access Gateway,” on page 1136 


Clustered Access Gateway 


If the hardware fails on an Access Gateway machine that belongs to a cluster: 
1 In Administration Console Dashboard, view the configuration of the cluster. Click Devices > 
Access Gateways. 


2 (Conditional) If the failed Access Gateway is the primary server, assign another server to be the 
primary server: 


2a On Access Gateways page, click [Name of Cluster] > Edit. 


2b For the Primary Server field, select another server to be the primary server, then click OK > 
Close. 


2c Click Identity Servers > Update. 


3 Delete the failed Access Gateway from the cluster. Click Access Gateways, select the failed 
Access Gateway, then click Actions > Remove from Cluster. 


IMPORTANT: Do not delete Access Gateway from Administration Console. 
4 On the new machine, install Access Gateway, specifying Administration Console, IP address, 
host name, and domain name of the failed machine. 


5 (Conditional) If you have customized error messages, copy the message files to Access 
Gateway. 


6 When the machine imports into Administration Console, add the machine to Access Gateway 
cluster: 


6a In Administration Console Dashboard, click Devices > Access Gateways. 


6b Select the name of Access Gateway, then click Actions > Assign to Cluster > [Name of 
Cluster]. 


6c Update Access Gateway. 
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28.5.2 Single Access Gateway 


Do not delete Access Gateway from Administration Console. If you delete Access Gateway from 
Administration Console, the configuration information is deleted. 


1 On the new machine, install Access Gateway by using Administration Console, IP address, host 
name, and domain name of the failed device. 
2 If you have customized error messages, copy the message files to Access Gateway. 


3 When the installation is completed and the device has been imported in Administration Console, 
verify the following: 


3a Check its trusted relationship with Identity Server. Click Devices > Access Gateways > Edit 
> Reverse Proxy / Authentication. 


3b If you have configured Access Gateway to use SSL, reconfigure the certificates for the 
listener. Click Devices > Access Gateways > Edit > [Name of Reverse Proxy]. 
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Code Promotion 


Code Promotion helps you replicate the configuration data of Access Manager from one setup to 
another. You can export the configuration data as a password-protected encrypted file, then import 
this file into another Access Manager system and seamlessly replicate the configuration into the 
target system. 


The exported configuration data includes generic Identity Server cluster configuration, customization 
files, proxy services, protected resources, and policy configuration. The exported data is independent 
of the device specific data and network specific data. Therefore, you can use Code Promotion to 
replicate configuration between two Access Manager systems that are in different networks, with a 
different number of devices, and with different user stores. 


+ Section 29.1, “How Code Promotion Helps,” on page 1137 

¢ Section 29.2, “Sequence of Promoting the Configuration Data,” on page 1138 
¢ Section 29.3, “Prerequisites,” on page 1138 

¢ Section 29.4, “Limitations,” on page 1139 

¢ Section 29.5, “Configuring Custom File Paths,” on page 1139 

¢ Section 29.6, “Exporting the Configuration Data,” on page 1140 

¢ Section 29.7, “Importing the Configuration Data,” on page 1141 

¢ Section 29.8, “Troubleshooting Code Promotion,” on page 1148 


29.1 How Code Promotion Helps 


Code promotion helps you seamlessly perform the following activities: 


¢ Managing multiple Access Manager setups: When managing multiple Access Manager 
setups, you may need to replicate the same configuration in all setups. 


For example, you want to test your configuration in a dedicated staging setup and then build a 
new production setup based on the tested configurations. Or, you maintain multiple staging 
setups and you want the configuration changes to pass through on these setups before 
deploying the configuration data to an existing production setup. You do not need to manually 
replicate the configuration data in other setups. 


Code Promotion provides a mechanism to move the configuration data across Access Manager 
setups. Code promotion increases efficiency, improves productivity, and in turn reduces costs of 
managing configurations across environments. 


+ Managing different setups by different administrators: Different administrators can manage 
different Access Manager environments. Manually replicating the configuration to different 
setups requires maintenance of a precise list of all changes done on one system and this 
knowledge must be transferred among administrators. Code Promotion takes all configuration 
changes and replicates correctly. 


¢ Replacing or moving physical devices: You may need to replace physical devices or move 
them to a different network due to a business decision, such as changing a network 
infrastructure vendor. For example, you want to move your application to another physical server 
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or you want to move the application hardware to a different network infrastructure. Code 
Promotion is independent of network-specific changes and helps you easily transfer the 
configuration data. 


+ Adding devices in the cluster: You have added a device in a cluster for capacity needs. When 
you add a device to a cluster, Access Manager applies the customization of that cluster to the 
device. 


+ Adding a new application or path: You have added a new application or a new path and you 
want to replicate it to another environment. 


+ Adding or modifying a protected resource: You have added or modified a protected resource 
and you want to replicate it to another environment. 


29.2 Sequence of Promoting the Configuration Data 


You must move the configuration data in the following sequence: 


1. Identity Server configurations, policies configurations, Certificates and Keystores configurations, 
and Identity Server custom files 


2. Access Gateway configurations and Access Gateway custom files 


NOTE: If you want to import only protected resources or proxy services along with the related Identity 
Server contracts, you need to import only Access Gateway configuration. Code Promotion also 
imports Identity Server dependencies. 


29.3 Prerequisites 


Ensure that you have read and implemented the following prerequisites before performing Code 
Promotion: 


+ The source server and the target server must have the same version of Access Manager. If you 
want to export the configuration data from an earlier version of Access Manager, ensure that you 
first upgrade Access Manager on the source server to the Access Manager version installed on 
the target server. For more information about how to upgrade Access Manager, see the 
“Upgrading Access Manager’ in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


+ The source server and the target server must run on the same operating system. 


+ The source server and the target server must have the same model; that is, both must be either 
Access Manager or Access Manager Appliance. 


¢ Importing configuration data replaces the existing configuration data. Therefore, use the backup 
option in the Import wizard to preserve a copy of the existing configuration before importing the 
data. 


+ Before you import Access Gateway configuration, you must manually create reverse proxies and 
master proxy services or root proxy service on the target system. 


¢ Each configuration entity that you want to map between source and destination systems should 
have the same name. Configuration entities include proxy service, protected resource, 
authentication class, method, contract, and user stores. 


+ Back up Access Gateway configuration by using the ambackup file. For more information, see 
Chapter 28, “Back Up and Restore,” on page 1129. 


The backup option available on the Code Promotion user interface works only for Identity Server 
configuration. 
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29.4 Limitations 


29.5 


The following list includes limitations in Code Promotion: 


+ Code Promotion supports export and import of only the generic configuration data. It does not 
support export and import of the configuration data that vary from one system to another. For 
example, you cannot export and import network specific configuration, device specific 
configuration, configuration store, and its replica ring configuration. 


¢ Customization files that you want to import should contain only generic information, not any 
device-specific information. For example, server.xml contains local keystore passwords. 
Therefore, you should not apply it to all devices. 


+ For Access Gateway, Code Promotion supports export and import of only proxy services and 
protected resources along with configured contracts and policies. 


+ Code Promotion does not support export or import of only custom files. 
+ Internet Explorer Compatibility View does not support Code Promotion. 


+ Code Promotion takes a significantly longer time on Windows, especially importing the metadata 
repository. You must wait until the import process is complete to avoid data corruption. 


+ Code Promotion does not support export or import of Appmarks configuration data. 


Configuring Custom File Paths 


Access Manager provides a configurable list of files and directories for Identity Server and Access 
Gateway to export. This list contains default paths of the most frequently customized files. If you have 
customized any additional files or you have saved the custom file at any other location instead of the 
default directory, you must update the path before initiating the export process. 


This list also contains paths of customized files for Access Manager installed Windows. You can 
ignore the paths if your setup is on Linux. 


Perform the following steps to configure the custom file paths: 


1 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Code Promotion > Settings. 


Use this tab only when you export the configuration data. You do not need to make any change 
in file paths while importing the configuration data. 


2 Ensure that the paths are correct. Update the default paths with the actual paths wherever 
applicable. 


NOTE: You must provide the complete name of the custom file. Code Promotion does not 
support wildcard characters in file names. For example: 


Supported: /opt/novell/nam/mag/webapps/agm/WEB-INF/config/current/ 
ErrorMessages.xml.en 


Not supported: /opt /novell/nam/mag/webapps/agm/WEB- INF/config/current/ 
ErrorMessages. xml. * 


3 Click OK. 


NOTE: Ensure that the custom files do not include any system-specific data. 
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29.6 Exporting the Configuration Data 


You can download previously exported configuration files. Access Manager saves these exported 
files on the primary Administration Console system also at the following location: 


/var/opt/novell/novlwww/namconfig 


You can delete or back up these files if needed. If you delete these files from the disk, the Code 
Promotion page does not list them any longer. 


The exported configuration data includes: 


¢ Identity Server configuration 

¢ Cluster configuration 

¢ Shared Settings 

¢ Identity Server policies 

+ Customization files 

+ Risk-based authentication configuration 
e Access Gateway configuration 

+ Proxy services and protected resources 

+ Access Gateway policies 

¢ Customization files 


NOTE: You cannot export configuration of an Access Gateway that is not part of any 
Access Gateway cluster. 


Perform the following steps to export the configuration data: 


1 Log in to Administration Console from where you want to export the configuration data. 


2 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Code Promotion. 


3 In the Code Promotion page, click Export Configuration. 
4 Based on your requirements, select the configuration to export: 


Identity Server Configuration: Exports all clusters, shared settings, keystores, trust stores, 
and Identity Server policies. You can also select to export Identity Server customization files, if 
any. 

Access Gateway Configuration: Exports proxy services, protected resources, and Access 
Gateway policies. You can also select to export Access Gateway customization files, if any. 
Code Promotion exports all Identity Server dependent configurations, such as contracts 
assigned to protected resources, even though you selected only Access Gateway configuration 
to export. 


If you want to export customization files, select respective devices to export customization files. 


NOTE 


¢ |f you saved a customization file at a location that is not a default location, ensure that you 
update the file name, directory name, and path before exporting the file. For more 
information, see Section 29.5, “Configuring Custom File Paths,” on page 1139. 


+ Code Promotion does not support import or export of only custom files. 
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29.7 


29.7.1 


5 Click Next. 
6 (Optional) Specify a password to encrypt the archived configuration data file. 


You require this password to decrypt the ZIP file while importing configuration data into another 
environment. 


7 Click OK and save on your local system. 


Importing the Configuration Data 


You can import the configuration data either for Identity Server or for Access Gateway at one time. 
You need to repeat the process to import the configuration data of each component. 


If you are importing the configuration data on a new production environment, you must import Identity 
Server configuration, and create reverse proxies and master proxy services before importing Access 
Gateway configuration data. 


Import the configuration data only on the primary Administration Console. Importing the configuration 
data includes the following actions: 

¢ Section 29.7.1, “Uploading Configuration File to Import,” on page 1141 

¢ Section 29.7.2, “Selecting the Component to Import the Configuration Data,” on page 1142 

¢ Section 29.7.3, “Importing Identity Server Configuration Data,” on page 1142 

¢ Section 29.7.4, “Importing Access Gateway Configuration Data,” on page 1143 

¢ Section 29.7.5, “Post-lmport Configuration Tasks,” on page 1146 


Uploading Configuration File to Import 


Perform the following steps to import the configuration data: 


1 Log in to Administration Console where you want to import the configuration data. 


2 In Administration Console Dashboard, click <user name> at the top right of the page and then 
click Code Promotion. 


3 In the Code Promotion page, click Import Configuration. 
4 Click Browse to import the configuration file. 


5 In Decryption Password, specify the password that you used to encrypt the configuration data 
file. You need this password to extract the contents of the configuration file. 


6 (Optional) Select Backup current configuration before import and Backup customization files. 
This backup helps to roll back your changes if needed. Code promotion encrypts the backup file 
with the same password that you specified for decryption in Step 5. You can download this 
backup file from the Code Promotion page. 


NOTE: This option backs up only Identity Server-specific configuration. To back up Access 
Gateway configuration, you must use the ambackup file. 


7 Click Next. Continue with Section 29.7.2, “Selecting the Component to Import the Configuration 
Data,” on page 1142. 
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29.7.2 Selecting the Component to Import the Configuration Data 


Code Promotion automatically detects whether the imported ZIP file contains configuration data of 
Identity Server, Access Gateway, or both. It also checks for any device customization files. 
1 Under Select Configuration To Import, select the option you need based on your requirements: 


¢ Identity Server Configuration: Select this option to import Identity Server configuration 
data. Select Customization Files on Devices if you want to import Identity Server 
customization files. 


+ Access Gateway Configuration: Select this option to import Access Gateway 
configuration data. Select Customization Files on Devices if you want to import Access 
Gateway customization files. 


2 (Only for Access Gateway) Under Access Gateway Cluster Mapping, specify the cluster in 
Source Cluster from which you want to export the configuration data and select the cluster in 
Target Cluster in which you want to import the configuration data. You can import configuration 
data of only one cluster at a time. If you want to import configuration from multiple clusters, run 
the import process separately for each cluster. 


3 Click Next. 


4 Continue with any one of the following sections based on the configuration you selected to 
import: 


¢ Section 29.7.3, “Importing Identity Server Configuration Data,” on page 1142. 
¢ Section 29.7.4, “Importing Access Gateway Configuration Data,” on page 1143. 


29.7.3 Importing Identity Server Configuration Data 


Importing Identity Server configuration data includes the following steps: 


. Uploading Configuration File to Import 
. Selecting the Component to Import the Configuration Data 
. Importing Identity Server Clusters 
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. Post-Import Configuration Tasks 


29.7.3.1 Importing Identity Server Clusters 


1 Inthe Import Identity Server Clusters section, specify the import action for each cluster available 
in the imported configuration. Select the desired options based on your requirements. 


NOTE: Importing Identity Server Configuration overwrites the existing Shared Settings on the 
system with new Shared Settings. However, if any of the existing settings on the target system 
are not part of the source system configuration, Code promotion will not delete them. 
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29.7.4 


The following table lists examples with Attribute Sets and import action: 


Imported Attribute Sets Existing Attribute Sets Import Action 


OIOSAML with five mappings OIOSAML with two mappings Replaces OIOSAML set with the 
imported one. It has five 


mappings. 
AttrSet1 Not available Adds AttrSet1. 
No import AttrSet2 is defined only in the AttrSet2 remains unchanged. 


target system 


2 In Clusters To Import, select a cluster to configure import settings. 
3 Select an action for the selected cluster from Import Action. 


+ Import As New Cluster: Select this option if you want to import the cluster as a new 
cluster. Ensure that the new cluster name is different from the existing cluster names 
defined on that system. 


¢ Overwrite Existing Cluster: Select this option if you want to overwrite the existing cluster 
with the selected cluster. 


NOTE: You need to configure the import action for each cluster separately. If the cluster you 
want to import has only one user store, Code Promotion maps the user store to the default user 
store of the existing cluster. If the cluster you are importing has multiple user stores, then you 
must specify how to map them to the user stores of the existing cluster. 


4 Click Next. 
Continue with Section 29.7.5, “Post-Import Configuration Tasks,” on page 1146. 


Importing Access Gateway Configuration Data 


Code Promotion uses names to associate entities from the source system to the target system. It 
searches on the source system for names that are part of the import. If it finds Access Gateway 
entities with the same names, it overwrites these entities. If not available, it creates new entries with 
the same names from the source system. When Identity Server and policies-specific entities with the 
same names are available, you can select whether to overwrite these. 


If the policy name, policy extension, and proxy service match on the source and target systems, but 
their type does not match, then the import does not happen. 


Code Promotion does not export Access Gateway clusters, reverse proxies, and master proxies. 
Before importing Access Gateway configuration data, you must manually create clusters, reverse 
proxies, and master or root proxy services in the target system. 


If you want to import Access Gateway protected resources that require Identity Server configuration 
other than contracts and its dependencies, LDAP attributes, and Shared Secret, you must first import 
the required Identity Server configuration. For example, for risk-based authentication or OAuth 
configuration, you need to import relevant Identity Server configuration separately. You can import 
these configurations manually or by using Identity Server Code Promotion. 


NOTE: If the reverse proxy in the source system is non-HTTP and in the target system it is HTTPS or 
vice-versa, ensure that you have tested the configuration before importing. In this case, the import 
may result in issues if there is any issue in the browser to Access Gateway communication. 
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29.7.4.1 


29.7.4.2 


Importing Access Gateway configuration data includes the following steps: 


. Uploading Configuration File to Import 

. Selecting the Component to Import the Configuration Data 

. Selecting Proxy Services and Protected Resources to Import 

. Verifying the Component-Specific Configuration Changes 

. Updating Identity Server User Store References 

. Setting Up New Proxy Services in the Target System after Import 
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. Post-lmport Configuration Tasks 


Selecting Proxy Services and Protected Resources to Import 


When you select a proxy service for import, all protected resources associated with this proxy service 
are selected automatically. You cannot deselect any protected resources of a selected proxy service 
for import. 


Code Promotion validates the content you want to import in to the target system. If there is any issue, 
it displays validation errors. 


Code Promotion imports Access Gateway customization details if you have selected the option. If any 
issue happens during customization files import, the system displays a message. You can continue or 
cancel the import process at that point. 


To select proxy services and protected resources to import, complete the following steps: 


1 The Code Promotion page displays the entire list of proxy services and protected resources from 
the source setup. Select proxy services and protected resources that you want to import. 


2 Click Next. Continue with “Verifying the Component-Specific Configuration Changes” on 
page 1144. 


Verifying the Component-Specific Configuration Changes 


Verify the details of configuration data that will be newly created and the data that will be overwritten 
on the destination system after import is complete. A proxy service may have a reference to logging 
profiles or http rewriter profiles. A protected resource refers to Identity Server contracts and policies. 
Identity Server contracts in turn refer to authentication class, methods, image sets, and user stores. A 
policy has a dependency on policy extensions, policy containers, Identity Server LDAP attributes and 
shared secrets. When you import Access Gateway configuration, all of these dependencies are 
imported. 


IMPORTANT: You can import only enabled rewriter and logging profiles, not the disabled profiles. 


Regardless of the type of logging profile (common or extended) and rewriter profile (word or 
character), if the name of the profile is same on both the source and target systems, Code Promotion 
overwrites the profile. 


To verify configuration changes, perform the following steps: 


1 Select Access Gateway to verify the details about proxy services, protected resources, rewriter 
profiles, logging profiles, authentication procedures, and Access Gateway certificates that you 
are importing. 
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If you are importing a proxy service to a production setup where the same proxy service exists, 
the system will not overwrite the following parameters and will retain these: 


+ Published DNS Name 
+ Host Header 

+ Web Server Host Name 
+ Connect Port 

+ Web Server List 


Access Manager locks Access Gateway cluster and policy containers and releases these only 
after the import is complete or if you cancel the process before completing import. 


2 Select Identity Server to verify the details about Identity Server contracts, methods, classes, 
LDAP attributes, shared secrets, and images that Code Promotion is importing along with 
Access Gateway configuration data. Select Overwrite Existing Contracts if you have made any 
changes in the existing configuration in the source system. Selecting this option overwrites the 
contracts and their dependencies, such as methods and classes, in the target system. If you do 
not select to overwrite, Code Promotion does not import the modified configurations to the target 
system. 


3 Select Policy to verify the details about policies, such as policy container and policy extension, 
that Code Promotion is importing along with Access Gateway configuration data. Code 
Promotion matches policy containers by names for importing policies. If the names do not match, 
it creates new policy containers with that name on the target system. Select Overwrite Existing 
Policies if you have made any change to the existing configuration in the source system. 
Selecting this option overwrites the policies and its dependencies (such as policy extension, 
LDAP attribute, and shared secret) in the target system. If you do not select to overwrite, Code 
Promotion does not import the modified configurations to the target system. 


After selecting Overwrite Existing Policies, LDAP attributes and Shared Secret values in Identity 
Server overview page may change. Verify the details and select Verified again on Identity Server 
overview page. 


4 Select Verified in each section. 
5 Click Next. Continue with “Updating Identity Server User Store References” on page 1145. 


Updating Identity Server User Store References 


If you have selected to overwrite a method or you have any new method that refers to a user store, 
update the reference of the user store of the source system to the user store of the target system. You 
can see the option to update user store references only when you select to overwrite a method or 
importing a new method. 


You cannot reference the same user store on the target system to multiple user stores on the source 
system. 


If the name of the user store on the source and target systems is the same, then the target system 
displays only that user store name that you should select. 


If you have created a new user store in the source system, Code Promotion imports only the name to 
the target system. You must add entries manually after completing the import process. 
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To update the user store reference on the target system, perform the following steps: 


1 Select the user store in Imported User Store and then select a corresponding user store in the 


target system under Existing User Store. Perform this activity for all imported user stores. 


2 Click Next. 


Continue with “Setting Up New Proxy Services in the Target System after Import” on page 1146. 


29.7.4.4 Setting Up New Proxy Services in the Target System after Import 


29.7.5 


To set up new proxy services in the target system, perform the following steps: 


1 Specify the following details for all newly created proxy services: 


NOTE: By default, all fields (Published DNS Name, Cookie Domain, Host Header, Web Server 
Host Name, Web Server List, and Connect Port) contain source system entries. 


Published DNS Name: (Only for domain-based proxy services) Specify the DNS name you 
want the public to use to access your site. This DNS name must resolve to the IP address you 
set up as a listening address on Access Gateway. The DNS name should be unique and not in 
use by any other proxy service. 


Cookie Domain: Specify the domain for which the cookie is valid. Cookie domain is set as the 
corresponding master proxy service's cookie domain for domain-based and path-based proxy 
services. For a virtual proxy service, you can select a cookie domain based on the DNS 
specified. 


Host Header: Specify the name you want to send in the HTTP header to the Web server. 


Web Server Host Name: Specify the DNS name of the Web server that Access Gateway should 
forward to the Web server. 


Web Server List: Specify Identity Server address or DNS name of Web servers. You can define 
it on cluster level. If you want to specify it for an individual server, go to Devices > Access 
Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Web Servers. You can 
specify a Web Server Host Name for an individual server. For more information, see 

Section 3.8.3, “Configuring Web Servers of a Proxy Service,” on page 126. 


Connect Port: Specify the port that Access Gateway uses to communicate with the Web server. 


2 Click Next. 
3 Click Finish when the import process is completed. Continue with “Post-lmport Configuration 


Tasks” on page 1146. 


Post-Import Configuration Tasks 


After importing Identity Server and Access Gateway configuration data, you must perform 
configurations that are specific to the target system and that are not part of the exported data. 


Tasks after importing Identity Server configuration data 


+ After the import process is complete, the system displays a list of certificates that you need to 


create or import manually and apply. Code promotion imports Identity Server key stores, but you 
must create the certificates referenced in them on the server where you have imported the 
configuration data. 


+ To create certificates, go to Security > Certificates. For more information about how to 
create certificates, see Section 13, “Creating Certificates,” on page 947. 
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+ The new certificate name must exactly match the names listed. 


+ Update Identity Server devices in the modified clusters. Go to Troubleshooting > 
Certificates and click Re-push certificates, and then update all devices in the cluster. 


¢ Configure user stores for the newly added clusters. After the import process is complete, the 
system displays a list of Identity Server clusters for which you need to configure user stores. 
Code Promotion creates a placeholder entry for the user store. Code Promotions sets eDirectory 
as the default user store. You must enter the IP address, search context, and the password for 
the user stores of the target system. For more information, see Section 5.1.1, “Configuring 
Identity User Stores,” on page 360. 


+ For a newly added cluster, you need to manually add Identity Server devices to it. This will 
enable you to use the imported configuration. 


¢ Distribute the policy extension JARs to devices in Administration Console under Policy > 
Extensions. For more information, see “Distributing a Policy Extension” on page 718. 


+ (Conditional) Update service providers with the new metadata. The identity provider certificate is 
different in the exported and imported systems. Therefore, you must re-import the identity 
provider metadata to all service providers in that cluster for federation to work. For more 
information, see “Viewing and Reimporting a Trusted Provider’s Metadata” on page 189. 


+ Code Promotion does not import persistent federation identities and shared secrets. Only 
Identity Servers in your exported setup and service providers share these. You must configure 
these on the server after you import the configuration data. 


+ When you add a new node in a cluster and no cache exists, the system takes customization of 
any active node in that cluster and applies that customization to this node on the target system. 
Modify the list of customization files to include all files as of the source setup. Otherwise, the 
customization available on the target system will be applied to the node. 


+ In case of User Attribute Retrieval and Transformation feature, after the import process is 
complete: 


¢ Ifa data source entry exists only in staging, then a new entry is created in the production 
environment. Code Promotion creates a placeholder entry for the data source fields. You 
must enter the username, password, IP, port, search context for LDAP, and URL of the data 
source 


+ Ifa data source entry exists in the staging and the production environment, and, if the data 
source name is the same but has a different data source type, then, the production entry is 
retained. 


Tasks after importing Access Gateway configuration data 


+ After the import process is complete, the system displays a list of certificates that you need to 
create or import manually and apply. Proxy key stores are imported, but you must create the 
certificates referenced in them on the target system. 


+ To create certificates, go to Security > Certificates. For more information about how to 
create certificates, see Section 13, “Creating Certificates,” on page 947. For more 
information about how to create certificates, see Section 13, “Creating Certificates,” on 
page 947. 


+ The new certificate name must exactly match with names listed. 


+ Go to Troubleshooting > Certificates to re-push certificates and then update all devices in 
the cluster. 


+ If SSL is enabled between the imported proxy services and the web servers, and you selected to 
verify the certificate authorities of the web server certificates, then ensure that the web server's 
trusted roots are added to Access Gateway's proxy trust store. 
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Go to Troubleshooting > Certificates to re-push certificates and then update all devices in the 
cluster. 


+ Configure the user store if you have imported a new user store. Configure or edit the user stores 
for Identity Server clusters associated with the target Access Gateway cluster. 


+ Update the following Identity Server dependencies of policies with appropriate Identity Server 
cluster names and data if any of the policies refer to these: 


+ Authentication contract, Liberty user profile, LDAP OU, Roles, LDAP group, credential 
profile, OAuth scope, and OAuth claims 


+ Java data injection modules (these are deprecated) 


+ If you have imported the policy extensions, distribute the policy extension JARs to the devices in 
Administration Console under Policy > Extensions and restart Access Gateway. If you imported 
policy extensions as part of Device Customization, then only restart Access Gateway. 


For more information, see “Distributing a Policy Extension” on page 718. 


+ When you add a new node in a cluster and no cache exists, the system takes customization of 
any active node in that cluster and applies that customization to this node on the target system. 
Modify the list of customization files to include all files as of the source setup. Otherwise, the 
customization available on the target system will be applied to the node. 


+ 


If the imported Access Gateway components or policies refer to anything other than the following 
Identity Server dependencies, then, you must import these dependencies manually by using 
Identity Server Code Promotion: Contracts, methods, classes, user stores, LDAP attributes, and 
shared secrets. 


29.8 Troubleshooting Code Promotion 


See Section 30.8, “Troubleshooting Code Promotion,” on page 1240. 
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0 Troubleshooting 


The following sections contain information about troubleshooting Access Manager components, 
features, policies, and certificates: 

¢ Section 30.1, “Troubleshooting Administration Console,” on page 1149 

¢ Section 30.2, “Troubleshooting Access Gateway,” on page 1169 

¢ Section 30.3, “Troubleshooting Identity Server and Authentication,” on page 1194 

¢ Section 30.4, “Troubleshooting Analytics Server,” on page 1218 

¢ Section 30.5, “Troubleshooting Certificate Issues,” on page 1221 

¢ Section 30.6, “Troubleshooting Access Manager Policies,” on page 1226 

¢ Section 30.7, “Troubleshooting MobileAccess,” on page 1238 

¢ Section 30.8, “Troubleshooting Code Promotion,” on page 1240 

¢ Section 30.9, “Troubleshooting the Device Fingerprint Rule,” on page 1244 

¢ Section 30.10, “Troubleshooting Advanced Session Assurance,” on page 1249 


¢ Section 30.11, “Troubleshooting XML Validation Errors on Access Gateway Appliance,” on 
page 1257 


¢ Section 30.12, “Troubleshooting OAuth and OpenID Connect,” on page 1263 

¢ Section 30.13, “Troubleshooting User Attribute Retrieval and Transformation,” on page 1266 
¢ Section 30.14, “Troubleshooting Impersonation,” on page 1267 

¢ Section 30.15, “Troubleshooting Branding,” on page 1268 

¢ Section 30.16, “Using Log Files for Troubleshooting,” on page 1269 

¢ Section 30.17, “Access Manager Audit Events and Data,” on page 1292 

¢ Section 30.18, “Event Codes,” on page 1341 


NOTE: For information about installation and upgrade troubleshooting, see “Troubleshooting 
Installation and Upgrade’ in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


30.1 Troubleshooting Administration Console 


This section provides information about general troubleshooting issues found in Administration 
Console: 

¢ Section 30.1.1, “Global Troubleshooting Options,” on page 1150 

¢ Section 30.1.2, “Diagnostic Configuration Export Utility,” on page 1153 

¢ Section 30.1.3, “Stopping Tomcat on Windows,” on page 1154 

¢ Section 30.1.4, “Logging,” on page 1154 

¢ Section 30.1.5, “Restoring a Failed Secondary Console,” on page 1154 

¢ Section 30.1.6, “Moving the Primary Administration Console to New Hardware,” on page 1155 
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30.1.1 


30.1.1.1 
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Section 30.1.7, “Converting a Secondary Administration Console into a Primary Console,” on 
page 1156 


Section 30.1.8, “Repairing the Configuration Datastore,” on page 1164 

Section 30.1.9, “Session Conflicts,” on page 1165 

Section 30.1.10, “Unable to Log In to Administration Console,” on page 1165 

Section 30.1.11, “(Linux) Exception Processing IdentityService_ServerPage.JSP,” on page 1166 


Section 30.1.12, “Backup and Restore Failure Because of Special Characters in Passwords,” on 
page 1166 


Section 30.1.13, “Unable to Install NMAS SAML Method,” on page 1166 
Section 30.1.14, “Incorrect Audit Configuration,” on page 1167 


Section 30.1.15, “Unable to Update Access Gateway Listening IP Address in Administration 
Console Reverse Proxy,” on page 1167 


Section 30.1.16, “During Access Gateway Installation Any Error Message Should Not Display 
Successful Status,” on page 1168 


Section 30.1.17, “Incorrect Health Is Reported on Access Gateway,” on page 1168 


Section 30.1.18, “Administration Console Does Not Refresh the Command Status 
Automatically,” on page 1169 


Section 30.1.19, “SSL Communication with Weak Ciphers Fails,” on page 1169 
Section 30.1.20, “Error: Tomcat did not stop in time. PID file was not removed,” on page 1169 
Section 30.1.21, “Access Manager Upgrade Hangs While Upgrading eDirectory,” on page 1169 


Global Troubleshooting Options 


The following options allow you to view the status of multiple devices and identify the devices that are 
not healthy. 


+ 


+ 


+ 


+ 


+ 


+ 


Section 30.1.1.1, “Checking for Potential Configuration Problems,” on page 1150 
Section 30.1.1.2, “Checking for Invalid Policies,” on page 1152 

Section 30.1.1.3, “Checking for Version Conflicts,” on page 1152 

Section 30.1.1.4, “Checking and Terminating User Sessions,” on page 1153 
Section 30.1.1.5, “Checking for Invalid Policies,” on page 1153 

Section 30.1.1.6, “Viewing System Alerts,” on page 1153 


Checking for Potential Configuration Problems 


If your Access Manager components are not behaving in the way you have configured them to run, 
you might want to check the system to see if any of the components have configuration or network 
problems. 


1 In Administration Console Dashboard, click Troubleshooting > Configuration. 


2 All of the options should be empty, except the Cached Access Gateway Configurations option 


(see Step 4) and the Current Access Gateway Configurations option (see Step 5). If an option 


contains an entry, you need to clear it. Select the appropriate action from the following table: 


Troubleshooting 


Option 


Device Pending with No Commands 


Other Known Device Manager 
Servers 


Access Gateways with Corrupt 
Protected Resource Data 


Access Gateways with Duplicate 
Protected Resource Data 


Access Gateways with Protected 
Resources Referencing 
Nonexistent Policies 


Access Gateways with Invalid Alert 
Profile References 


Devices with Corrupt Data Store 
Entries 


Description and Action 


If you have a device that remains in the pending state, even when 
all commands have successfully executed, that device appears 
in this list. Before deleting the device from this list, check its 
Command Status. If the device has any commands listed, select 
the commands, then delete them. Wait a few minutes. If the 
device remains in a pending state, return to this troubleshooting 
page. Find the device in the list, then click Remove. 
Administration Console clears the pending state. 


If a secondary Administration Console is in a non-reporting state, 
perhaps caused by hardware failure, its configuration needs to be 
removed from the primary Administration Console. As long as it 
is part of the configuration, other Access Manager devices try to 
contact it. If you cannot remove it by running the uninstall script 
on the secondary Administration Console, you can remove it by 
using this troubleshooting page. Click Remove next to the 
console that is in the non-reporting state. All references to the 
secondary Administration Console are removed from the 
configuration database. 


If you modify the configuration for a protected resource, update 
Access Gateway with the changes, then review the configuration 
for the protected resource and the changes have not been 
applied, the configuration for the protected resource is corrupted. 
Click Repair next to the protected resource that has a corrupted 
configuration. You should then be able to modify its configuration, 
and when you update Access Gateway, the changes should be 
applied and saved. 


After an upgrade, if you get errors related to invalid content for 
policy enforcement lists, you need to correct them. The invalid 
elements that do not have an associated resource data element 
are listed in this section. Click Repair. 


Protected resources have problems when policies are deleted 
before their references to the protected resources are removed. If 
you have protected resources in this condition, they are listed in 
this section. Click the Repair button to remove these references. 
Then verify that your protected resources have the correct 
policies enabled. Click Access Gateways > Edit > [Name of 
Reverse Proxy] > [Name of Proxy Service] > Protected 
Resources, then change to the Policy View. 


You can create XML validation errors on your Access Gateway 
Appliance if you start to create an alert profile (click Access 
Gateways > Edit > Alerts > New), but you do not finish the 
process. The incomplete alert profile does not appear in the 
configuration for Access Gateway, so you cannot delete it. If such 
a profile exists, it appears in the Access Gateways with Invalid 
Alert Profile References list. Click Remove. You should then be 
able to modify its configuration, and when you update Access 
Gateway, the changes should be applied and saved. 


If an empty value is written to an XML attribute, the device with 
this invalid configuration appears in this list. 


Click Repair to rewrite the invalid attribute values. 
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3 When you have finished repairing or deleting invalid Access Gateway configurations, click the 
Access Gateways link, then click Update > OK. 


4 (Optional) Verify that all members of an Access Gateway cluster have the same configuration in 
cache: 


4a Click Troubleshooting > Configuration. 
4b Scroll to the Cached Access Gateway Configuration option. 
4c Click View next to the cluster configuration or next to an individual Access Gateway. 


This option allows you to view Access Gateway configuration that is currently residing in 
browser cache. If Access Gateway belongs to a cluster, you can view the cached 
configuration for the cluster as well as the cached configuration for each member. The + 
and - buttons allow you to expand and collapse individual configurations. The configuration 
is displayed in XML format 


To search for particular configuration parameters, you need to copy and paste the text into a 
text editor. 


5 (Conditional) After viewing Access Gateway configuration (see Step 4) and discovering that an 
Access Gateway does not have the current configuration, select Access Gateway in the Current 
Access Gateway Configurations section, then click Re-push Current Configuration. 


30.1.1.2 Checking for Invalid Policies 


The Policies page displays the policies that are in an unusable state because of configuration errors. 


1 In Administration Console Dashboard, click Troubleshooting > Policies. 
If you have configured a policy without defining a valid rule for it, the policy appears in this list. 
2 Select the policy, then click Remove. 


30.1.1.3 Checking for Version Conflicts 


The Version page displays all the installed components along with their currently running version. Use 
this page to verify that you have updated all components to the latest compatible versions. There are 
two steps to ensuring that your Access Manager components are running compatible versions: 


+ All components of the same type should be running the same version. If you have components 
that display multiple versions, identify the components that need to be upgraded and upgrade 
them to the newer version. 


+ All components need to be running versions that are compatible with each other. 
To view the current version of all Access Manager devices: 


1 In Administration Console Dashboard, click Troubleshooting. 
2 Click Version. 


A list of the devices with their version information is displayed. If a device also has an Embedded 
Service Provider, the version of the Embedded Service Provider is also displayed. 
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30.1.1.4 


30.1.1.5 


30.1.1.6 


30.1.2 


Checking and Terminating User Sessions 


The User Sessions page helps you to find users logged into your system and also helps to terminate 
their sessions if required. It displays the active user details for each Identity Server. You can search 
for a user with the user ID and terminate the session(s). 

1 In Administration Console Dashboard, click Troubleshooting > User Sessions. 


2 Specify the user ID and click Search. If a match is found, it lists the IP address of Identity Server 
and its sessions. 


3 Click Terminate Sessions to terminate the sessions of the specific user. 


NOTE: User details are fetched once per administration session. The last updated date is 
displayed. To refresh the data, click on Refresh. 


For more information about user sessions, see Section 30.3.28, “Terminating an Existing 
Authenticated User from Identity Server,” on page 1214. 


Checking for Invalid Policies 
The Policies page displays the policies that are in an unusable state because of configuration errors. 


1 In Administration Console Dashboard, click Troubleshooting > Policies. 
If you have configured a policy without defining a valid rule for it, the policy appears in this list. 
2 Select the policy, then click Remove. 


Viewing System Alerts 


The System Alerts page displays how many unacknowledged alerts have been generated for all the 
devices imported into this Administration Console. 


1 In Administration Console Dashboard, click Alerts. 


2 To acknowledge and clear the alerts for a device, select the name of the server, then click 
Acknowledge Alerts. 


The following columns display information about the alerts for each server. 


Column Description 


Server Name Specifies the name of the server receiving alerts. Click the server name to view 
more information about an alert before acknowledging it. 


Severe Indicates how many severe alerts have been sent to the server. 
Warning Indicates how many warning alerts have been sent to the server. 
Informational Indicates how many informational alerts have been sent to the server. 


Diagnostic Configuration Export Utility 


In Administration Console, you can create a .1dif file that you can export for diagnostic purposes: 


1 Loginas root. 
2 On Linux: Change to the /opt/novell/devman/bin directory and run the following command: 
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./amdiagcfg.sh 


On Windows: Go to the C:\Program Files (x86)\Novell\bin directory and run the following 
command: 


./amdiagcfg.bat 

Specify the Access Manager administrator's password. 

Specify the path where you want to store the diagnostic file. 

Specify a name for the diagnostic file. The system adds .xml automatically as file extension. 


on Ff O 


Press Enter. 


The Diagnostic Configuration Export utility is almost identical to the backup utility because it also 
creates a LDIF file with an addition of an XML Dump file. Passwords from the final LDIF file are 
removed by a program called Strippasswd. 


Strippasswd removes occurrences of passwords in the LDIF file and replaces them with empty 
strings. If you look at the LDIF file, you will see that password strings are blank. You might see 
occurrences within the file or text that looks similar to password=“String”. These are not instances of 
passwords, but rather definitions that describe passwords as string types. 


With every Access Manager release you must copy the corresponding XML style sheet file (XSL file) 
to the same directory where the XML file is located. This helps in displaying the information in correct 
format. The XSL file is located at /opt/novell/devman/bin. 


The XML file along with XSL file or LDIF file (if required) can then be sent to NetIQ Support for help in 
diagnosing configuration problems. 


30.1.3 Stopping Tomcat on Windows 


If you use Administrative Tools > Services on Windows to stop Tomcat, Tomcat does not shut down 
cleanly and displays an error. To continue, click OK. 


The following command sometimes produces an error: 
net stop Tomcat7 


Whichever method you use to stop Tomcat, Tomcat is stopped. Wait a minute before restarting 
Tomcat. 


30.1.4 Logging 


You can troubleshoot by configuring component logging. Click Devices > Identity Server > Edit > 
Auditing and Logging. 


For more information, see Section 30.16, “Using Log Files for Troubleshooting,” on page 1269. 


30.1.5 Restoring a Failed Secondary Console 


If a secondary console fails, you need to remove its configuration from the primary console before 
installing a new secondary console. If the failed console is part of the configuration, other Access 
Manager devices try to contact it. 

1 On the primary console, click Troubleshooting. 


2 In the Other Known Device Manager Servers section, click Remove next to the secondary 
console that is failed. 
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3 Remove traces of the secondary console from the configuration datastore: 

3a In the Access Manager menu bar, select View Objects. 

3b In the Tree view, select novell. 

3c Delete all objects that reference the failed secondary console. 

You should find the following types of objects: 

¢ SAS Service object with the hostname of the secondary console 
+ An object that starts with the last octet of the IP address of the secondary console 
+ DNS AG object with the hostname of the secondary console 
+ DNS IP object with the hostname of the secondary console 
¢ SSL CertificateDNS with the hostname of the secondary console 
¢ SSL CertificatelP with the hostname of the secondary console 


4 Install a new secondary console. For installation instructions, see Section 9.1, “Installing 
Secondary Versions of Administration Console,” on page 883. 


Moving the Primary Administration Console to New 
Hardware 


If you do not have any secondary consoles: 
1 Perform a backup. For instructions, see Section 28.2, “Backing Up the Access Manager 
Configuration,” on page 1130. 


2 Install Administration Console of the same type (Linux or Windows) on the new hardware using 
the same DNS name and IP address. 


3 Restore the configuration. For instructions, see Section 28.3, “Restoring the Access Manager 
Configuration,” on page 1131. 


If you have secondary consoles, you need to re-create the replica ring. When you install secondary 
consoles, they are added to the replica ring of the configuration datastore. The Access Manager 
backup script does not back up the replica ring information. It backs up only the Access Manager 
configuration information. The following instructions explain how you can re-create the replica ring 
when you install the primary Administration Console on new hardware. 


1 Perform a backup. For instructions, see Section 28.2, “Backing Up the Access Manager 
Configuration,” on page 1130. 
2 Down any secondary consoles. 


3 Install Administration Console on the new hardware using the same DNS name and IP address 
that is used for the existing Primary Console. 


4 Restore the configuration. For instructions, see Section 28.3, “Restoring the Access Manager 
Configuration,” on page 1131. 


5 Remove any secondary consoles from the configuration: 
5a In Administration Console Dashboard, click Troubleshooting. 


5b In the Other Known Device Manager Servers section, use the Remove button to remove 
any secondary consoles. 


6 Uninstall the secondary consoles. For instructions, see Uninstalling the Administration Console 
in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


7 Reinstall the secondary consoles as secondary consoles to the new primary console. 
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30.1.7 


30.1.7.1 


30.1.7.2 


NOTE: Taking the backup of Administration Console configuration on one platform such as Linux and 
restoring it to another platform such as on Windows or vice versa is not supported. 


Converting a Secondary Administration Console into a 
Primary Console 


To convert a secondary Administration Console into a primary Administration Console, a recent 
backup of Administration Console must be available. For information about how to perform a backup, 
see Section 28.2, “Backing Up the Access Manager Configuration,” on page 1130. A backup is 
necessary to restore the certificate authority (CA). 


If the failed server holds a master replica of any partition, you must use ndsrepair to designate a 
new master replica on a different server in the replica list. 


WARNING: Perform these steps only if the primary Administration Console cannot be restored. If you 
have a recent backup, you can restore the primary Administration Console to new hardware. This is 
an easier configuration task than converting a secondary console into a primary console. See 
Section 30.1.6, “Moving the Primary Administration Console to New Hardware,” on page 1155. 


This conversion includes the following tasks: 


¢ Section 30.1.7.1, “Shutting Down Primary Administration Console,” on page 1156 

¢ Section 30.1.7.2, “Changing the Master Replica,” on page 1156 

¢ Section 30.1.7.3, “Restoring CA Certificates,” on page 1158 

¢ Section 30.1.7.4, “Verifying the vcdn.conf File,” on page 1158 

¢ Section 30.1.7.5, “Deleting Objects from the eDirectory Configuration Store,” on page 1159 
¢ Section 30.1.7.6, “Performing Component-Specific Procedures,” on page 1159 


Shutting Down Primary Administration Console 


If your primary Administration Console is running, you must log in as the administrator and shut down 
the service. 


¢ Linux: Start YaST, click System > System Services (Runlevel), then select to stop the ndsd 
service. 


+ Windows: Open the Control Panel, click Administrative Tools > Services, then select to stop 
the x64 NDS Server. 


Changing the Master Replica 


Changing the master replica to reside on the new primary Administration Console makes this 
Administration Console into the certificate authority for Access Manager. You need to first designate 
the replica on the new primary Administration Console as the master replica. Then you need to 
remove the old primary Administration Console from the replica ring. 


¢ “Linux Secondary Administration Console” on page 1157 


e “Windows Secondary Administration Console” on page 1157 
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Linux Secondary Administration Console 


1 


At secondary Administration Console, log in as root. 


2 Change to the /opt/novell/eDirectory/bin directory. 


w 


o ON OW RA 


Run DSRepair with the following options: 

./ndsrepair -P -Ad 

Select the one available replica. 

Select Designate this server as the new master replica. 
Run ndsrepair -P -Ad again. 

Select the one available replica. 

Select View replica ring. 

Select the name of the failed primary server. 

Select Remove this server from replica ring. 

Specify the DN of the admin user in leading dot notation. For example: 
-admin.novell 

Specify password. 

Type I Agree when prompted. 

Continue with “Restoring CA Certificates” on page 1158. 


Windows Secondary Administration Console 
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At secondary Administration Console, log in as an administrator. 

Change to the C: \Novel1\NDS directory. 

Start the NDSCons.exe program. 

Select dsrepair .d1m. 

In the Parameters box, specify -A, then click Start 

Click Partitions > Root > Designate This Server As The New Master Replica. 
Open Partitions > Root, select the server, and verify that the replica is the master replica. 
Run dsrepair again with -A in the Parameters box. 

Click Partitions > Root, then select the name of the failed primary server. 
From the menu, click Partitions > Replica Rings > Remove Server From Ring. 
Specify the DN of the admin user in leading dot notation. For example: 
-admin.novell 

Specify password. 

Continue with “Restoring CA Certificates” on page 1158. 
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30.1.7.3 Restoring CA Certificates 


Perform the following steps on the machine that you are promoting to be a primary console. 
1 Copy your most recent Administration Console backup files to your new primary Administration 
Console. 
2 Ona Windows 2012 server, open the Registry Editor using the regedit command. 
2a Traverse to \HEKY_LOCAL_MACHINE\SOFTWARE\NOVELL\AccessManager \Devman key. 
2b Update the value of the key with the IP address of the new Primary Administration Console. 
3 Change to the backup bin directory: 
Linux: /opt/novell/devman/bin 
Windows Server 2012: \Program Files (x86)\Novell\bin 


4 Verify the IP address in the backup file. The IP_Address parameter value should be the IP 
address of the new Primary Administration Console. 


4a Open the backup file: 
Linux: defbkparm. sh 
Windows: defbkparm. properties 


4b Verify that the value in the IP_Address parameter is the IP address of your new primary 
console. 


4c Save the file. 
5 Run the certificate restore script: 
Linux: sh aminst-certs.sh 
Windows: aminst-certs.bat 
6 When prompted, specify the administrator's password and location of the backup files. 
7 Continue with “Verifying the vcdn.conf File” on page 1158. 


30.1.7.4 Verifying the vcdn.conf File 


Verify whether the vcdn.conf file contains IP address of the new Administration Console. If it 
contains IP address of the failed primary Administration Console, replace it with the new IP address. 
1 Change to the Administration Console configuration directory: 
Linux: opt/novell/devman/share/conf 


Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\roma\WEB- 
INF\conf 


2 Run the following command in the command line interface to restart Administration Console: 
Linux: /etc/init.d/novell-ac restart or rcnovell-ac restart 
Windows: net stop Tomcat7 
net start Tomcat7 


3 Continue with “Deleting Objects from the eDirectory Configuration Store” on page 1159. 
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30.1.7.5 Deleting Objects from the eDirectory Configuration Store 


Objects representing the failed primary Administration Console in the configuration store must be 
deleted. 
1 Log in to the new Administration Console, then click Troubleshooting. 


2 In the Other Known Device Manager Servers section, select the old primary Administration 
Console, then click Remove. 


3 Remove traces of the failed primary Administration Console from the configuration datastore: 
3a In the Access Manager menu bar, select View Objects. 
3b In the Tree view, select novell. 
3c Delete all objects that reference the failed primary Administration Console. 
You should find the following types of objects: 
+ SAS Service object with the hostname of the failed primary console 
+ An object that starts with the last octet of the IP address of the failed primary console 
+ DNS AG object with the hostname of the failed primary console 
+ DNS IP object with the hostname of the failed primary console 
¢ SSL CertificateDNS with the hostname of the failed primary console 
¢ SSL CertificatelP with the hostname of the failed primary console 
+ NCP server object 
4 Continue with “Performing Component-Specific Procedures” on page 1159. 


30.1.7.6 Performing Component-Specific Procedures 


If you have installed the following components, perform the cleanup steps for the component: 


¢ “Identity Server Installed with the Failed Primary Administration Console” on page 1159 
¢ “Third Administration Console” on page 1160 

+ “Access Gateway Appliances” on page 1160 

+ “Access Gateway Services” on page 1162 

¢ “Linux Identity Server” on page 1163 

e “Windows Identity Server” on page 1164 

¢ “Old Primary Administration Console” on page 1164 


Identity Server Installed with the Failed Primary Administration Console 


If you had an Identity Server installed with your failed primary Administration Console, you need to 
clean up the configuration database to remove references to this Identity Server. 
1 Log in to Administration Console. 
2 Remove Identity Server: 
2a Click Devices > Identity Servers. 
2b Select Identity Server that was installed with the primary Administration Console. 
2c Remove it from the cluster, then delete it. 
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Third Administration Console 


If you installed a third Administration Console used for failover, you must manually perform the 
following steps on that server: 
1 Open the vcdn.conf file. 
Linux: /opt/novell/devman/share/conf 


Windows Server 2012: \Program Files (x86)\Novell\Tomcat \webapps\roma\WEB- 
INF\conf 


2 In the file, look for the line that is similar to the following: 
<vcdnPrimaryAddress>10.1.1.1</vcdnPrimaryAddress> 
In this line, 10.1.1.1 represents the failed primary Administration Console IP address. 
3 Change this IP address to the IP address of the new primary Administration Console. 


4 Restart the Administration Console by entering the following command from the command line 
interface: 


Linux: /etc/init.d/novell-ac restart OR rcnovell-ac restart 
Windows: Use the following commands: 
net stop Tomcat7 


net start Tomcat? 


Access Gateway Appliances 


For each Access Gateway Appliance imported into Administration Console, edit the 
settings.properties file on Access Gateway if the primary Administration Console was not 
configured as the Audit Server. The settings.properties file is required for JCC Communication 
between devices and Administration Console. 


If the primary Administration Console was configured as an Audit Server, you must edit the 
config.xml file and the settings. properties file on Access Gateway and edit the CurrentConfig 
and WorkingConfig XML documents in the configuration store on the new primary Administration 
Console. 


When the Primary Administration Console Was not Configured as the Audit Server 


1 AtAccess Gateway Appliance, log in as the root user. 

2 Open a terminal window and shut down all services by entering the following command: 
/etc/init.d/novell-appliance stop 

3 Edit the settings.properties file: 
3a Enter: vi /opt/novell/devman/jcc/conf/settings.properties 


3b Change the IP address in the remotemgmt ip list from the IP address of the failed 
Administration Console to the address of the new primary Administration Console. 


3c Enter :wq! to save and exit. 
4 AtAccess Gateway Appliance, start all services by entering the following commands: 
/etc/init.d/novell-appliance start 


5 (Conditional) Repeat this process for each Access Gateway that has been imported into 
Administration Console. 
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When the Primary Administration Console Was Configured as the Audit Server 


1 AtAccess Gateway Appliance, log in as the root user. 

2 Open a terminal window and shut down all services by entering the following command: 
/etc/init.d/novell-appliance stop 

3 Edit the config. xml file: 
3a Enter vi /opt/novell/nam/mag/webapps/agm/WEB - INF/config/current/config. xml 
3b Enter /Remote, then press Enter. 


In the IPv4Address field, change the IP address from the failed Administration Console to 
the new primary Administration Console address. 


3c Enter /NsureAuditSetting, then press Enter. 


In the IPv4Address field, change the IP address from the failed Administration Console to 
the new primary Administration Console address. 


3d Enter :wq! to save and exit. 
4 Edit the settings. properties file: 
4a Enter: vi /opt/novell/devman/jcc/conf/settings.properties 


4b Change the IP address in the remotemgmt ip list from the IP address of the failed 
Administration Console to the address of the new primary Administration Console. 


4c Enter :wq! to save and exit. 


5 At the new primary Administration Console, open an LDAP browser and edit the CurrentConfig 
object of Access Gateway Appliance. 


IMPORTANT: You should use an LDAP browser for the following steps, rather than iManager. 
Because iManager is slow at saving large files, your iManager connection might time out before 
your modifications are saved. 


5a Browse to the following container: novell > accessManagerContainer > VCDN_Root > 
PartitionsContainer > Partition > AppliancesContainer. 


A list of devices appears. Access Gateways have an ag prefix. 

5b Expand an Access Gateway container, then select the CurrentConfig object. 

5c Select the romaAGConfigurationXMLDoc attribute and open it so you can view its value. 
The value is a large XML file. 

5d Copy the contents of the attribute to a text editor. 


5e (Conditional) To verify which Access Gateway Appliance you are changing, search for the 
<Local> element. 


The IP address should match the IP address of Access Gateway Appliance that you are 
configuring for the new primary Administration Console. 


5 


5g Change the IP address of the <Remote> element so that it matches the IP address of the 
new primary Administration Console. 


= 


Search for the <Remote> element. 


5h Search for the <NsureAuditSetting> element. 


Change the IP address of the <NsureAuditSetting> element so that it matches the IP 
address of the new primary Administration Console. 
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5i Copy the modified document in the text editor to the value field of the 
romaAGConfigurationXMLDoc attribute. 


5j Save your changes. 


6 At the new primary Administration Console, edit the WorkingConfig object of Access Gateway 
Appliance: 


Use an LDAP browser for these steps. 


6a Browse to the following container: novell > accessManagerContainer > VCDN_Root > 
PartitionsContainer > Partition > AppliancesContainer. 


A list of devices appears. Expand Access Gateway container. 
6b Select the WorkingConfig object. 
6c Select the romaAGConfigurationXMLDoc attribute and open it so you can view its value. 
6d Copy the contents of the attribute to a text editor. 
6e Search for the <Remote> element. 
6 


=> 


Change the IP address of the <Remote> element so that it matches the IP address of the 
new primary Administration Console. 


6g Search for the <NsureAuditSetting> element. 


Change the IP address of the <NsureAuditSetting> element so that it matches the IP 
address of the new primary Administration Console. 


6h Copy the modified document in the text editor to the value field of the 
romaAGConfigurationXMLDoc attribute. 


6i 
7 AtAccess Gateway Appliance, start all services by entering the following command: 


Save your changes. 


/etc/init.d/novell-appliance start 


8 (Conditional) Repeat this process for each Access Gateway that has been imported into 
Administration Console. 


Access Gateway Services 


For each Access Gateway Service imported into Administration Console, edit the 
settings.properties file on Access Gateway if the primary Administration Console was not 
configured as the Audit Server. 


If the primary Administration Console was configured as an Audit Server, you must edit the 
config.xml file and the settings .properties file on Access Gateway and edit the CurrentConfig 
and WworkingConfig XML documents in the configuration store on the new primary Administration 
Console. 
1 AtAccess Gateway Service, log in as the root or the Administrator user. 
2 Shut down all Access Gateway Services. 
Linux: Enter the /etc/init.d/novell-appliance stop command. 
Windows: Click Control Panel > Administrative Tools > Services, then stop the following 
services: 


Apache Tomcat 
JcCServer 


Stopping Apache Tomcat causes Apache 2.2 to also stop. 
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3 (Conditional) If your audit server was on the primary Administration Console, edit the 
config. xml file: 


3a Change to the directory and open the file. 
Linux: /opt/novell/nam/mag/webapps/agm/WEB- INF/config/current/config. xml 
Windows: \Program Files\Novell\Tomcat\webapps\agm\ WEB-INF\config\current 
3b Find the NsureAuditSetting entry. 


In the IPv4Address field, change the IP address from the failed Administration Console to 
the new primary Administration Console address. 


3c Save and exit. 
4 Edit the settings.properties file: 
4a Change to the directory and open the file. 
Linux: /opt/novell/devman/jcc/conf 
Windows: \Program Files\Novell\devman\jcc\conf 


4b Change the IP address in the remotemgmt ip list from the IP address of the failed 
Administration Console to the address of the new primary Administration Console. 


4c Save and exit. 

5 AtAccess Gateway Service, start all services by entering the following command: 
Linux: /etc/init.d/novell-appliance start OR rcnovell-appliance start 
Windows: Click Control Panel > Administrative Tools > Services, then start the following 
services: 


Apache Tomcat 
JcCServer 


Starting Apache Tomcat causes Apache 2.2 to also start. 


6 (Conditional) Repeat this process for each Access Gateway Service that has been imported into 
Administration Console. 


Linux Identity Server 
For each Linux Identity Server imported into Administration Console, perform the following steps: 


1 Log in as the root user. 
2 Open a terminal window and shut down all services by entering the following commands: 
+ /etc/init.d/novell-jcc stop OR rcnovell-jcc stop 
+ /etc/init.d/novell-idp stop OR rcnovell-idp stop 
3 Edit the settings.properties file: 
3a Enter vi /opt/novell/devman/jcc/conf/settings.properties 


3b Change the IP address in the remotemgmt ip list from the IP address of the failed 
Administration Console to the address of the new primary Administration Console. 


3c Enter :wq! to save and exit. 
4 Start the services by entering the following commands: 
¢ /etc/init.d/novell-jcc start OR rcnovell-jcc start 
+ /etc/init.d/novell-idp start OR rcnovell-idp start 
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Windows Identity Server 
For each Windows Identity Server imported into Administration Console, perform the following steps: 


1 Open a terminal window and shut down all services by entering the following commands: 
net stop JCCServer 
net stop Tomcat7 
2 Edit the settings.properties file: 
2a Change to the following directory: 
Windows Server 2012: \Program Files (x86)\Novell\devman\jcc\conf 
2b Open the settings. properties file. 


2c Change the IP address in the remotemgmtip list from the IP address of the failed 
Administration Console to the address of the new primary Administration Console. 


2d Save your changes. 
3 Start the services by entering the following commands: 
net start JCCServer 


net start Tomcat? 


Old Primary Administration Console 


After the secondary console has been promoted to be the primary console, uninstall Administration 
Console software of the old primary Administration Console. Before uninstalling, make sure the 
machine is disconnected from the network. For instructions, see Uninstalling the Administration 
Console in the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


If you want to use the old primary console as a secondary console, you need to first uninstall 
Administration Console software. Connect the machine to the network, then reinstall the software, 
designating this console as a secondary console. 


![removed Enabling Backup on the New Primary Administration Console as it is bydefault enabled for 
later versions. Confirmed with Surabhi Bali] 


30.1.8 Repairing the Configuration Datastore 


The configuration datastore is an embedded version of eDirectory. If it becomes corrupted, you can 
run DSRepair to fix it. Or, you can restore a recent backup. To restore a backup, see Section 28.3, 
“Restoring the Access Manager Configuration,” on page 1131. 


To run DSRepair: 
1 Ina browser, enter the following URL. 
http://<ip_address>:8028/nds 


Replace <jp_address> with the IP address of your Administration Console. 


2 At the login prompt, enter the username and password of the admin user for Administration 
Console. 


The NDS iMonitor application is launched. For more information, see Accessing iMonitor (http:// 
www.novell.com/documentation/edir88/edir88/data/a6l60f7.html). 


3 In the View bar, select the Repair icon. 
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30.1.9 


30.1.10 


For more information about DSRepair, see the following: 


+ Click the Help icon. 
+ Using NdsRepair 


Session Conflicts 


Do not use two instances of the same browser to simultaneously access the same Administration 
Console. Browser sessions share settings, which can result in problems when you apply changes to 
configuration settings. However, you can use two different brands of browsers simultaneously, such 
as Internet Explorer and Firefox to avoid the session conflicts. 


Unable to Log In to Administration Console 


If you experience problems logging in to Administration Console, you might need to restart Tomcat. 


1 Ina terminal window on the console machine, restart Tomcat: 

Linux: Enter the following command: 

/etc/init.d/novell-ac restart OR rcnovell-ac restart 

Windows: Enter the following commands: 

net stop Tomcat7 

net start Tomcat7 

If this does not solve the problem, check the log file: 

Linux: /opt/novell/nam/adminconsole/logs/catalina.out 

Windows Server 2012: \Program Files (x86)\Novell\Tomcat\logs\stdout.log 
Check for the following error: 


Error Starting up core services. 
Application manager is Shutting down the Device Manager suite. 
Shutting down Device Manager suite. 


4 (Linux) If you see this error, check the status of eDirectory: 


4a Enter the following command: 

/etc/init.d/ndsd status 

If the status command returns nothing, start eDirectory manually. 
4b Enter the following command: 

/etc/init.d/ndsd start 
4c Restart Tomcat. 


5 (Windows) If you see this error, check the status of eDirectory: 


5a Enter the following command: 
net start "nds server" 


If the service has been started, this command returns a message that the service has been 
started. If the service has been stopped, its starts eDirectory. 


5b Verify that the agent is running. Click Control Panel > Novell eDirectory Services, then 
verify that the Server box does not contain an agent closed message. 


5c If the agent is closed, run dsrepair. 
5d Restart Tomcat. 
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30.1.11 


30.1.12 


30.1.13 


(Linux) Exception Processing 
IdentityService_ServerPage.JSP 


If you see the message Exception processing IdentityService_ServerPage.jsp on a Linux 
Administration Console, it is an indication that the system has run out of available file handles. You 
need to use the command line to increase the ulimit value (ulimit -n [new limit]), which sets the 
number of open file descriptors allowed. 


To set this value permanently, you can create the /etc/profile. local file with the ulimit value, such 
as: 


ulimit -n 4096 


You can make changes to /etc/security/limits.conf file with a line just to change the limit for a 
specific user. In this case: novlwwuser. Add the following line: 


novlwww soft nofile [new limit] 


Backup and Restore Failure Because of Special Characters 
in Passwords 


Administration passwords with special characters such as dollar signs might cause the ambkup utility 
to fail. The ambkup utility creates a command line for the ICE utility, and the special characters might 
be interpreted by it. If you must use special characters, and this issue arises, modify the defbkparm 
file so that the special characters are escaped. 


For example, if the administrator's password is mi$$le, then the field DS_ADMIN_PWD should be 
mi\$\$le. 


This file is located in the following directory: 
Linux: /opt/novell/devman/bin/defbkparm. sh 


Windows Server 2012: \Program Files (x86)\Novell\bin\defbkparm. properties 


Unable to Install NMAS SAML Method 


When you try to create an Identity Server cluster configuration with an eDirectory user store and with 
the Install NMAS SAML method option enabled and you have not installed the dependent packages, 
the following error message is displayed: 


Warning: Failed to create SAML Affiliate Object 
com.novell.security.japi.nmas.LoginMethodModel.getLsmWINNNTStatus()I 


One of the installation requirements for the Linux Administration Console is to install the compat and 
the libstdc++ packages.On SLES 11, the compat package contains the libstdc++ library. Identity 
Server also requires the compat package. For more information about installing these packages, see 
TID 7006437. 
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30.1.14 Incorrect Audit Configuration 


If the Audit Events from Access Gateway behind NAT are not seen in the Audit Server, do the 
following: 


Click Auditing In Administration Console Dashboard and verify if values are provided for the Server 
Listening IP Address, Server Public NAT IP Address, and Port Numbers fields. 


Scenario 1: 
1 If the values are not provided for the Server Listening IP Address, Server Public NAT IP 
Address, and Port Numbers fields, enter the values, then click Apply. 
2 If you change the existing values and click Apply, the following message is displayed: 


Step 1: Update all Access Gateways. 

Step 2: To update the configuration files in Administration Console, see the 
context-sensitive help. 

Step 3: Reboot all servers to start using the new configuration. 


3 Click OK. 


4 Update Access Gateway whose events are not seen. 
5 Restart Access Gateway. 


Scenario 2: 


1 If Server Listening IP Address, Server Public NAT IP Address and Port Numbers are valid and 
still have problems, repush the configuration. 


2 Change the port number to some invalid port number, then click Apply. 


NOTE: Do not update or restart Access Gateway as the message indicates. 


3 Change the invalid port number again to the valid port number, then click Apply. 
The configuration is repushed and works successfully. 

4 Update Access Gateway whose events are not seen. 

5 Restart Access Gateway. 


30.1.15 Unable to Update Access Gateway Listening IP Address in 
Administration Console Reverse Proxy 


Administration Console fails to change Access Gateway listening IP address of the Reverse Proxy. 
The health status of Access Gateway on Administration Console displays failure to start the protected 
resource with old Listening IP address. However, when protected resource is viewed (Devices > 
Access Gateways > Access Gateway or Access Gateway Cluster > Proxy), Administration Console 
displays the new IP Address has been selected as listening IP address of the Reverse Proxy. 


To workaround this issue: 


1 Click Devices > Access Gateways. 
la Click the Health icon of Access Gateway that has the problem. 
1b Note the Reverse Proxies that have the problem. 


2 Click Devices > Access Gateways > Edit. 
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3 For each of the Reverse Proxies that have the problem, do the following: 
3a Click Reverse Proxy. 
3b Select the cluster member from the list. 
3c Select the new IP address on which the proxy service will listen to. 
3d Unselect the old IP address on which proxy service was listening to. 
3e Click OK. 
3f An alert is displayed as "Select at least one listening address for the service." 
3g Click OK. 
3h Again select Listening IP Address. 
3i Click OK. 

4 lf the update link is enabled, click it. If not, do the following: 


4a Click Edit for the cluster that has problem. 

4b Click the Proxy name link. 

4c Click Proxy service name in the Proxy Service list. 
4d Enter the description and click OK. 


After the device command status moves to Succeeded, verify the health status of Access Gateway. 


30.1.16 During Access Gateway Installation Any Error Message 
Should Not Display Successful Status 


Even after successful installation or upgrade of Access Gateway, the health shows failure in starting 
ESP. After an fresh import of Access GatewayAccess Manager Appliance in Administration Console, 
Access Gateway Health displays “ESP Failed to initialize : Unable to read <keystorefilelocation>”. 
The keystore file can be Connector, Signing, Encryption or Truststore. 


To workaround this issue: 
1 On Access Gateway, go to the <keystorefilelocation> location as specified in the health error 
message. 
2 Delete the keystore/truststore indicated in the ESP error message. 
3 In Administration Console Dashboard, click TroubleShooting > Certificates. 


4 Enable the keystore device or cluster that has been deleted in the Access Gateway and it needs 
to be re-pushed. 


5 Click Re-Push Certificate. 
6 Restart server provider of Access Gateway. 


30.1.17 Incorrect Health Is Reported on Access Gateway 


In Administration Console, if the Stop Service on Audit Server Failure option is enabled, Access 
Gateway services are stopped and show the Health status reports services as down when the Audit 
server is not functioning or reachable. 


If the Stop Service on Audit Server Failure option is disabled, Access Gateway Service comes up but 
the related Health status still reports the services as being down. 


To workaround this issue restart Tomcat. 
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30.1.18 


30.1.19 


30.1.20 


30.1.21 


30.2 


Administration Console Does Not Refresh the Command 
Status Automatically 


The automatic refresh feature to retrieve device health is disabled when total number of Access 
Gateway devices imported to an Administration Console page is more than 20. This feature is 
disabled to prevent the performance overhead in getting the health of 20 or more devices 
simultaneously. 


To workaround this issue an administrator can manually refresh the page to get the health status of 
the devices. 


SSL Communication with Weak Ciphers Fails 


Access Manger supports only the 128-bit SSL communication among Administration Console, 
Identity Server, and browsers. 


If you want to enable the weak ciphers (not recommended), see Section 17.7, “Configuring the SSL 
Communication,” on page 996. 


Error: Tomcat did not stop in time. PID file was not removed 


While stopping Tomcat for Administration Console, Access Gateway, or Identity Server, you may get 
this error message: 


Tomcat did not stop in time. PID file was not removed. 


Ignore this message. Tomcat will be forcibly stopped if it does not stop normally. 


Access Manager Upgrade Hangs While Upgrading 
eDirectory 


On Windows 2012 R2 Server, the Access Manager upgrade hangs while upgrading eDirectory. This 
occurs because the nservmsg.d11 file gets locked. This is a random issue. 


To workaround this issue, perform the following steps: 


1 Manually stop the Windows Event Log service. 
2 On the upgrade pop-up screen, click Retry. 
3 Restart the Windows Event Log service manually again and proceed with the upgrade. 
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¢ Section 30.2.1, “Useful Troubleshooting Files,” on page 1170 
¢ Section 30.2.2, “Verifying That All Services Are Running,” on page 1174 


¢ Section 30.2.3, “Microsoft Office Documents Do Not Open When SharePoint Is Accelerated by 
Access Gateway Appliance,” on page 1176 


¢ Section 30.2.4, “Troubleshooting SSL Connection Issues,” on page 1176 
¢ Section 30.2.5, “Enabling Debug Mode and Core Dumps,” on page 1177 
¢ Section 30.2.6, “Useful Troubleshooting Tools for Access Gateway Service,” on page 1179 
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¢ Section 30.2.7, “Solving Apache Restart Issues,” on page 1180 


¢ Section 30.2.8, “Understanding the Authentication Process of Access Gateway Service,” on 
page 1183 


¢ Section 30.2.9, “Enabling Caching of Audit Events for Apache Gateway Service,” on page 1189 
¢ Section 30.2.10, “Issue While Accelerating the Ajax Applications,” on page 1190 


+ Section 30.2.11, “Accessing Lotus-iNotes through Access Gateway Asks for Authentication,” on 
page 1190 


¢ Section 30.2.12, “Configuration Issues,” on page 1190 
¢ Section 30.2.13, “The Embedded Service Provider Does not Start,” on page 1190 
+ Section 30.2.14, “Cannot Inject a Photo into HTTP Headers,” on page 1191 


¢ Section 30.2.15, “Reimporting Access Gateway Takes the IP Address of the Old Administration 
Console,” on page 1191 


+ Section 30.2.16, “Reimporting Access Gateway Service Fails on Windows 2012 R2 Server,” on 
page 1191 


+ Section 30.2.17, “Access Gateway Caching Issues,” on page 1191 


¢ Section 30.2.18, “Issues while Changing Management IP Address in Access Gateway 
Appliance,” on page 1192 


+ Section 30.2.19, “Issue While Adding Access Gateway in a Cluster,” on page 1193 


+ Section 30.2.20, “Access Gateway Fails to Start After Upgrading SLES 11 SP3 to SLES 12,” on 
page 1194 


30.2.1 Useful Troubleshooting Files 


Access Gateway Service consists of two main modules, a Gateway Manager module that runs on top 
of Tomcat and a Proxy Service module that runs on top of Apache. Figure 30-1 illustrates these 
modules and the communication paths that Access Gateway Service has with other devices. 
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Figure 30-1 Access Gateway Service Modules 
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Proxy Service: This component runs as an instance of Apache and is responsible for controlling 
access to the configured protected resources on web servers. Low-level errors are reported in the 
Apache logs. Some higher-level errors are also reported to the files in the amlogging/logs directory. 


ESP: The Embedded Service Provider is responsible for handling all communications with Identity 
Server and is responsible for the communication that verifies the authentication credentials of users. 
Log entries for this communication process, including errors, are logged in the catalina. out file and 
the stdout . log file. 


ActiveMQ: This module is used for real-time communication between Administration Console and 
the Proxy Service. Errors generated from the Gateway Manager to the ActiveMQ module are logged 
to the Tomcat logs. Errors generated from the Proxy Service to the ActiveMQ module are logged to 
the Apache error logs. 


JCC: The Java Communication Controller is the interface to Administration Console. It handles 
health, statistics, configuration updates, and purge cache requests from Administration Console. It is 
also responsible for certificate management. Errors generated between the JCC module and the 
Gateway Manager are logged to the ags_error . log file. Errors generated between Administration 
Console and the JCC module are logged to the jcc-@.1og.x file 


Gateway Manager: This module is responsible for handling communication from JCC to the Proxy 
Service. It also writes the configuration commands to the Apache configuration files and the Proxy 

Service configuration file on disk. Errors generated while performing these tasks are logged to the 

ags_error.1log file. 
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User Session Cache: Access Gateway Service has one additional module, a User Session Cache 
module. This module is responsible for managing user information across all Proxy Service 
processes. Any errors generated by this module are logged to the Apache error logs. 


For more information about these various log files, see the following: 


¢ Section 30.2.1.1, “Apache Logging Options for Gateway Service,” on page 1172 
¢ Section 30.2.1.2, “Access Gateway Service Log Files,” on page 1173 


Apache Logging Options for Gateway Service 


The Proxy Service module of Access Gateway Service is built on top of Apache as an Apache 
application. This module handles the browser requests for access to resources and is responsible for 
sending authorized requests to the Web servers. Entries for these events are logged to the Apache 
log files. 


If Access Gateway Service log files do not contain enough information to solve a problem (see 
Section 21.4.1, “Managing Access Gateway Logs,” on page 1048), you might want to view the 
contents of the Apache log files. These files are located in the following directory: 


Linux: /var/log/novell-apache2/ 
Windows: C:\Program Files\Novell\apache\logs\ 


For more information, see sections “Ignoring Some Standard Messages” on page 1172 and 
Section 21.4.1, “Managing Access Gateway Logs,” on page 1048. 


Ignoring Some Standard Messages 


Apache cannot detect the proper use of domain-based multi-homing with wildcard certificates, which 
allows multiple proxy services to share the same SSL port. If you create reverse proxy services that 
are configured for domain-based multi-homing with SSL, Apache considers this a possible port 
conflict and logs it as a warning in the error . log file. 


The error messages look similar to the following: 


[<time and date stamp>] [warn] Init: SSL server IP/port conflict: 
dbmhnsnetid.dsm.cit.novell.com:443 (C:/Program 
Files/Novell/apache/conf/vhosts.d/dbmhNS-NetID.conf:18) vs. 
magwini430external.dsm.cit.novell.com:443 (C:/Program 
Files/Novell/apache/conf/vhosts.d/magMaster .conf:18) 


[<time and date stamp>] [warn] Init: SSL server IP/port conflict: 
magdbmheguide.dsm.cit.novell.com:443 (C:/Program 
Files/Novell/apache/conf/vhosts.d/dbmhMagEguide.conf:18) vs. 
magwini430external.dsm.cit.novell.com:443 (C:/Program 
Files/Novell/apache/conf/vhosts.d/magMaster .conf:18) 


You can ignore these errors because Access Gateway Service knows how to handle the traffic and 
send the packets to the correct proxy service. 


For more information about Apache log files, see “Log Files” (http://httpd.apache.org/docs/2.2/ 
logs.html). 


Modifying the Logging Level for the Apache Logs 


If the Apache error log file does not contain enough information, you can modify the log level and the 
types of messages written to the file. 
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WARNING: If you set the log level to debug, the size of the file can grow quickly, consume all 
available disk space, and crash the system. If you change the log level, you need to carefully monitor 
available disk space and the size of the error log file. 


To modify what is written to the Apache error log file: 


1 Change to the Apache configuration directory. 
Linux: /etc/opt/novell/apache2/conf 
Windows: C:\Program Files\Novell\apache\conf 
2 Open the httpd.conf file. 
3 Find the LogLevel directive and set it to one of the following: 
debug, info, notice, warn, error, crit, alert, emerg 
4 Save the file. 
5 Restart Apache: 
Linux: /etc/init.d/novell-apache2 restart OR rcnovell-apache2 restart 
Windows: Use the following commands: 
net stop apache2.2 
net start apache2.2 


6 (Optional) If you set the level to debug and the log file still does not supply enough information, 
see Section 30.2.5, “Enabling Debug Mode and Core Dumps,” on page 1177. 


Access Gateway Service Log Files 


See Section 21.5.5, “Linux Access Gateway Appliance and Access Gateway Service Logs,” on 
page 1060 and Section 21.5.6, “Windows Access Gateway Service Logs,” on page 1061. You can 
gather these log files into a single zip file: 


Zipping the Files on Windows Access Gateway Service 


On Windows, you can use the getlogs. bat file to gather all of these log files into a zip file. You need 
to have 7-Zip (a free download) installed in order to run the batch file. The batch file is located in the 
\programfiles\Novell\unsupported directory. To run the file 

1 Copy getlogs.bat to the C:\programfiles\Novell\unsupported directory. 

2 Copy the 7-Zip file (7za.exe) to the C: \programfiles\Novell\unsupported directory. 

3 Enter the following command: 


getlogs <filename> 


You can specify a filename. If one is not specified, the file is called out. You can modify the batch 
file to use a different default name. 


The file is created in the current working directory. 


The batch file includes only files that are not currently in use. If you need to include the most recent 
version of a log file, you need to stop Access Gateway Service. 
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30.2.2 Verifying That All Services Are Running 


¢ Section 30.2.2.1, “Linux,” on page 1174 
¢ Section 30.2.2.2, “Windows,” on page 1175 


30.2.2.1 Linux 


1 Log in to the server as the root user. 
2 Verify that the ActiveMQ service is running by entering the following command: 


# ps -ef | grep activemg 
Aline similar to the following is displayed: 


root 23453 1 © Mar21 ? 01:43:27 /opt/novell/java/bin/java - 
Xmx512M -Dorg.apache.activemq.UseDedicatedTaskRunner=true - 
Dcom.sun.management.jmxremote -Djavax.net.ssl.keyStorePassword=password - 
Djavax.net.ssl.trustStorePassword=password -Djavax.net.ssl.keyStore=/opt/ 
novell/activemq/conf/broker.ks -Djavax.net.ssl.trustStore=/opt/novell/ 
activemg/conf/broker.ts -Dactivemg.classpath=/opt/novell/activemg/conf; - 
Dactivemq.home=/opt/novell/activemq -Dactivemq.base=/opt/novell/activemq -jar 
/opt/novell/activemgq/bin/run.jar start 

root 28753 28643 © 12:18 pts/0 00:00:00 grep --color=auto activemgq 


3 Verify that one or more Apache proxy services are running by entering the following command: 
ps -ef | grep httpd 
Lines similar to the following are displayed: 


root 2983 30290 © 12:53 pts/Q 00:00:00 egrep httpd 

root 3163 1 © May12 ? 00:00:29 /opt/novell/apache2/sbin/httpd 
wwwrun 3165 3163 © May12 00:01:00 /opt/novell/apache2/sbin/httpd 
wwwrun 3184 3163 © May12 00:00:01 /opt/novell/apache2/sbin/httpd 
wwwrun 3188 3163 © May12 00:00:01 /opt/novell/apache2/sbin/httpd 


Nn Nv 


4 Verify that the user session cache service is running by entering the following command: 
ps -ef | grep novell-agscd 
Lines similar to the following are displayed: 


root 3259 30290 © 12:56 pts/0 00:00:00 egrep novell-agscd 
108 5525 1 © May11 ? 00:00:00 /opt/novell/ag/bin/novell-agscd -d 
108 5526 5525 © May11 ? 00:00:09 /opt/novell/ag/bin/novell-agscd -d 


5 Verify that the Tomcat service is running by entering the following command: 
ps -ef | grep catalina.base 


Lines similar to the following are displayed: 
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ps -eaf | grep catalina.base 

novlwww 28764 1 © Jul05 pts/O 00:02:05 /opt/novell/java/bin/java -Dnop 
-server -Xmx2048m -Xms512m -Xssi28k -Djava.library.path=/usr/1ib64:/opt/ 
novell/eDirectory/1ib64:/opt/novell/1ib64 - 
Dcom.novell.nam.common.util.DeploymentMode=MAGAppliance - 
Dsun.net.client.defaultConnectTimeout=29000 - 
Dsun.net.client.defaultReadTimeout=28000 -Dnids.freemem.threshold=10 - 
Djavax.net.ssl.sessionCacheSize=10000 - 
Dsun.net.http.allowRestrictedHeaders=true -Djava.awt.headless=true - 
Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager - 
Djava.endorsed.dirs=/var/opt/novell/tomcat7/endorsed -classpath /lib/ 

tools. jar:/var/opt/novell/tomcat7/bin/bootstrap.jar:/var/opt/novell/tomcat7/ 
bin/tomcat-juli.jar -Dcatalina.base=/opt/novell/nam/mag -Dcatalina.home=/var/ 
opt/novell/tomcat7 -Djava.io.tmpdir=/opt/novell/nam/mag/temp 
org.apache.catalina.startup.Bootstrap -config /opt/novell/nam/mag/conf/ 
server.xml start 


6 Verify that the JCC service is running by entering the following command: 
ps -ef | grep /opt/novell/devman/jcc/conf/run.sh 
Lines similar to the following are displayed: 


root 3777 30290 © 13:03 pts/© 00:00:00 egrep /opt/novell/devman/jcc/ 
conf/run.sh 

root 5506 1 © May11 ? 00:00:00 /bin/bash /opt/novell/devman/jcc/ 
conf/run.sh 


When you are familiar with the services, you can use the following command to display 
information about all the services: 


ps -ef | egrep "novell-activemq|novell-agscd|/opt/novell/devman/jcc/conf/ 
run.sh|catalina.base|httpd" 


7 If one or more services are not running, use the following commands to start the services: 
/etc/init.d/novell-jcc start OR rcnovell-jcc start 
/etc/init.d/novell-apache2 start OR rcnovell-apache2 start 
/etc/init.d/novell-agcsd start 
/etc/init.d/novell-activemq start OR rcnovell-activemq start 
/etc/init.d/novell-mag start OR rcnovell-mag start 

8 If a service does not start, view the log files to determine the cause. See the following: 

¢ Section 30.2.7, “Solving Apache Restart Issues,” on page 1180 
+ “Access Gateway Service Log Files” on page 1173 


30.2.2.2 Windows 


1 Log in to the machine as the administrator. 
2 Click Control Panel > Administrative Tools > Services. 
3 Ensure that the following services are running: 
ActiveMQ 
Apache Tomcat7 
Apache2.2 
JCCServer 
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4 If one or more services are not running, select the service and start it. 

5 Ifa service won't start, view the log files to determine the cause. See the following: 
¢ Section 30.2.7, “Solving Apache Restart Issues,” on page 1180. 
e “Access Gateway Service Log Files” on page 1173 


30.2.3 Microsoft Office Documents Do Not Open When SharePoint 
Is Accelerated by Access Gateway Appliance 


You can access and view the files on the SharePoint server after authenticating at Identity Server. 
However, when you open the Microsoft Office documents from the browser for modifying, you get a 
HTTP 409 error even after you add the #NAGGlobalOptions AllowMSWebDavMiniRedir advanced 
option. 


The workaround is to add the 'Content-Disposition' header in response to the WebDAV queries. 


1 Add the following line to the httpd.conf available at /etc/opt/novell/apache2/conf/ file. 
LoadModule headers_module /libexec/mod_headers.so 


2 Add following entries to httpd.conf file 


<LocationMatch ".*\.doc$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.docx$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.xls$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.xlsx$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.ppt$"> 

Header set Content-Disposition attachment 
</LocationMatch> 
<LocationMatch ".*\.pptx$"> 

Header set Content-Disposition attachment 
</LocationMatch> 


3 Restart novell-apache2 services. 


30.2.4 Troubleshooting SSL Connection Issues 


SSL handshakes fail when there is a discrepancy between the cipher suites and cipher strengths 
used by the clients and the servers. If you enable SSL connections between Access Gateway and the 
browser or between Access Gateway and the Web servers, you need to make sure that both sides 
are configured to support the same cipher suites and cipher strengths. This is especially important if 
you enable the options to enforce 128-bit encryption (see “Configuring TCP Listen Options for 
Clients” on page 157). 


Access Gateway Service relies upon Apache to perform the SSL handshake, and Apache does not 
log the cause of SSL handshake failures, even when the log level is set to debug. To determine 
whether cipher strengths are the source of your problem, disable the options to enforce 128-bit 
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encryption (see “Configuring TCP Listen Options for Clients” on page 157). If users are then able to 
authenticate, verify the cipher strengths, which are configured for the browsers and for the Web 
servers, are compatible with Access Gateway. 


Enabling Debug Mode and Core Dumps 


If the log files are not generating enough information to identify the cause of a problem, you can run 
Access Gateway Service in debug mode. You should not be running in debug mode except when you 
are trying to isolate a problem because of the following side effects: 


+ Debug mode causes the size of the log files to grow quickly. They can grow large enough to 
consume all available disk space and crash the system. When running in debug mode, you need 
to carefully monitor available disk space and the size of the log files. 


+ Debug mode opens additional ports. Anyone who has local access to Access Gateway machine 
can see the information displayed in the following local URLs: 


http://127.0.0.1:8181/server-status 
http://127.0.0.1:8181/server-info 


+ Debug mode causes load and response times to slow. 


Debug mode enables core dumps, X-Mag headers in LAN traces, and increases log levels by 
enabling advanced option in Access Gateway configuration. For example LogLevel debug. This will 
set apache log level to debug in the error_log file. 


You can generate core dumps in the following two ways: 
1 Start /etc/init .d/novell-apache2 in debug mode. When there is a crash, core file will be 
created as /var/cache/novell-apache2/core. 
2 Without starting novell-apache2 in debug mode, perform the following: 
2a Setulimit -c unlimited in /etc/init.d/novell-apachez2 startup script. 


2b You can create the core directory under /tmp. Choose the file path based on the availability 
of disk space. Give the following command to create a directory in Access Gateway 
component: 


# mkdir -p /tmp/apache2-gdb-dump 
2c Set permission as follows: 
# chown novlwww:www /tmp/apache2-gdb-dump 
# chmod 0777 /tmp/apache2-gdb-dump 
2d Add the following advanced option in Access Gateway configuration as follows: 
CoreDumpDirectory /tmp/apache2-gdb-dump 
2e Apply changes to Access Gateway. 


Whenever there is a crash, core file will be created as/tmp/apache2-gdb-dump/core. 


For some crashes, the /tmp/debug000. log file is created. For more information about the log, see 
TID 7011804. 


This section describes the following tasks: 


¢ Section 30.2.5.1, “Starting Apache in Debug Mode,” on page 1178 
¢ Section 30.2.5.2, “Examining the Debug Information,” on page 1178 
¢ Section 30.2.5.3, “Disabling Debug Mode,” on page 1178 
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30.2.5.1 Starting Apache in Debug Mode 


Use the following commands to start debug mode: 

Linux: /etc/init.d/novell-apache2 stop OR rcnovell-apache2 stop 
/etc/init.d/novell-apache2 start debug OR rcnovell-apache2 start debug 
Windows: Use the following steps to enable debug mode: 


1 Create a tmp directory at the root of C: 
2 Stop Apache: 
2a Click Control Panel > Administrative Tools > Services. 
2b Right-click the Apache 2.2 service, then select Stop. 
3 Start Apache: 
3a Right-click the service, then click Properties. 
3b In the Start parameters box, specify 
-D allowServerDebug 
3c Click Start. 


30.2.5.2 Examining the Debug Information 


1 Examine the Apache error log file or copy it so you can send it to NetIQ Technical Support: 
Linux: /var/log/novell-apache2 
Windows: \Program Files\Novell\apache\logs 
2 View the information at the local URLs or copy the pages to send to NetIQ Support: 
+ http://127.0.0.1:8181/server-status 
This page displays debug information about caching, SSL, workers, and proxy information. 
¢ http://127.0.0.1:8181/server-info 
This page displays module and configuration information. 


3 Ifa crash occurred, examine the core dump file or copy it so you can send it to NetIQ Technical 
Support. 


Linux: /var/cache/novell-apache2 


Windows: C:\tmp directory that you created 


30.2.5.3 Disabling Debug Mode 


Use the following commands to disable debug mode: 

Linux: /etc/init.d/novell-apache2 stop OR rcnovell-apache2 stop 
/etc/init.d/novell-apache2 start nodebug OR rcnovell-apache2 start nodebug 
Windows: Use the following steps to disable debug mode: 


1 Click Control Panel > Administrative Tools > Services. 
2 Right-click the Apache 2.2 service, then select Stop. 

3 Right-click the service, then click Properties. 

4 in the Start parameters box, remove 
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-D allowServerDebug 
5 Click Start. 


30.2.6 Useful Troubleshooting Tools for Access Gateway Service 


Table 30-1 describes some of the tools available in Administration Console for solving potential 
problems: 


Table 30-1 Useful Tools 


Tool Description 


Re-push Current Configuration If you have an Access Gateway that does not seem to be using the 
current configuration, you can use Administration Console to push the 
current configuration to Access Gateway. Click Troubleshooting. In 
the Current Access Gateway Configuration section, select an 
Access Gateway, then click Re-push Current Configuration. 


Health icon In Administration Console, click the Health icon to view details about 
the health of Access Gateway. For more information, see 
Section 24.4.1, “Monitoring the Health of an Access Gateway,” on 
page 1102. 


Tools for specific platforms are also available. 


¢ “Tools for Windows Access Gateway Service” on page 1179 
¢ “Tools for Linux Access Gateway Service” on page 1179 


30.2.6.1 Tools for Windows Access Gateway Service 


The Windows operating system has the following tools that can help you determine the cause of a 


problem: 

Tool Description 

Task Manager Use this utility to check resources available on the system. 
Control Panel > Administrative Use this utility to stop and start services. 


Services > Services 


netstat -a Use this command to view statistics about the listeners on Access 
Gateway. 


30.2.6.2 Tools for Linux Access Gateway Service 


The Linux operating system has the following tools that can help you determine the cause of a 


problem: 
Tool Description 
curl Use this command to view identity provider metadata from Access 


Gateway. See “Testing Whether the Provider Can Access the 
Metadata” on page 1203. 
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Tool Description 


netstat -a Use this command to view statistics about the listeners on Access 
Gateway. 
tail -f Use this command to view real time activity in key log files. For 


information about useful files to tail, see “Access Gateway Service 
Log Files” on page 1173. 


top Use this command to check resources available on the system. 


tcpdump Use this command to capture data on standard and loopback 
interfaces and to view SSL data with imported keys. 


30.2.7 Solving Apache Restart Issues 
When you make configuration changes and update Access Gateway, Administration Console uses 


the JCC channel to send the configuration changes to Access Gateway. Figure 30-2 illustrates this 
flow. 


Figure 30-2 Sending Configuration Updates to Access Gateway 


Access Gateway Service 


Administration 
Console 


I Configuration Update 


Apache 
Restart 


JCC sends the configuration changes to Access Gateway Manager (AGM), which writes the Apache 
configuration to disk. Apache is sent a restart command, which causes Apache to read the new 
configuration, then Apache validates the configuration. 

¢ Ifthe configuration is valid, Apache starts. 

¢ Ifthe configuration is invalid, Apache fails to start. 
If Apache fails to start after a configuration change, roll back to the previous configuration. Restore a 
backup if you have one, or use Administration Console to manually remove the modifications that 
have caused the problem. If this does not solve the problem, try the following: 

¢ Section 30.2.7.1, “Removing An Advanced Configuration Settings,” on page 1181 

¢ Section 30.2.7.2, “Viewing the Logged Apache Errors,” on page 1181 

¢ Section 30.2.7.3, “Viewing the Errors as Apache Generates Them,” on page 1181 

¢ Section 30.2.7.4, “The ActiveMQ Module Fails to Start,” on page 1182 
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30.2.7.1 Removing An Advanced Configuration Settings 


Apache fails to start when it discovers a syntax error in any of the advanced options. 


1 Click Devices > Edit > Advanced Options. 
2 To reset all options to their default values, delete all options from the text box. 
3 Click OK. 
When you return to the Advanced Options page, all options are set to their default values. 
4 Click [Name of Reverse Proxy] > [Name of Proxy Service] > Advanced Options. 
5 To reset all options to their default value, delete all options from the text box. 
6 Click OK. 
When you return to the Advanced Options page, all options are set to their default values. 
7 Repeat these steps for each proxy service that has advanced options configured. 
8 Update Access Gateway. 


30.2.7.2 Viewing the Logged Apache Errors 
Apache generates and logs errors when it fails to start. A summary is displayed on the health page. 


1 In Administration Console Dashboard, click Devices > Access Gateways > Health. 


The page displays a summary of the problem from the Apache error log file. For Access 
Gateway Service, information from the rcnovell-apache2.out file might also be displayed. 


2 To view the entire contents of the Apache error log file, open a terminal window to Access 
Gateway. 


3 Change to the following directory and open the Apache error log file. 
Linux: /var/log/novell-apache2 
Windows: \Program Files\Novell\Apache\logs 

4 On Linux, view the contents of the rcnovell-apache2.out file. 


5 If you still do not have enough information to solve the configuration problem, continue with 
“Viewing the Errors as Apache Generates Them” on page 1181. 


30.2.7.3 Viewing the Errors as Apache Generates Them 


Apache allows only a few errors to be sent to log files. To view all the errors, use the following 
procedure to display the errors in a terminal window. 


1 Copy the config. xml file in the current directory to a temporary location. Access Gateway 
allows only one XML file to reside in the current directory. 
Linux: /opt/novell/nam/mag/webapps/agm/WEB- INF/config/current 
Windows: \Program Files\Novell\Tomcat \webapps\agm\WEB- INF\config 

2 Copy the XML file from the pending directory to the current directory and rename it config. xml. 
The file in the pending directory has a long numeric name. 

3 (Linux) Change the ownership of the file from root to novlwww: novlwww. 

4 Use one of the following commands to restart Tomcat: 
Linux: /etc/init.d/novell-mag restart OR rcnovell-mag restart 


Windows: Use the following commands: 
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net stop Tomcat7 
net start Tomcat7 
5 (Linux) Restart Apache by using the following command: 
/etc/init .d/novell-apache2 restart OR rcnovell-apache2 restart 


Apache uses the terminal window to write the errors it discovers as it tries to process the 
config. xml file. 


6 (Windows) Run Apache in debug mode: 
6a Use the following command to stop Apache: 
net stop apache2.2 
6b Change to the \Program Files\novell\apache\bin directory. 
6c Enter the following command: 
httpd -e Debug 


Apache writes to the terminal window the errors it discovers as it tries to processes the 
config. xml file. 


7 AtAdministration Console, fix the configuration problems, then update Access Gateway. 


The ActiveMQ Module Fails to Start 
The Active MQ module is used for real-time communication between Administration Console and 


Access Gateway Service. Real-time communication is needed for commands such as purging cache, 
gathering statistics, and updating health. Figure 30-3 illustrates this communication flow. 


Figure 30-3 Real-Time Communication 
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When the ActiveMQ module fails to start, you cannot apply any configuration changes, and Access 
Gateway does not set a listener for the configured port. 


To start the module, it must be able to resolve the listening IP address to a DNS name. To install an 
Access Gateway Service, the machine must have a DNS name and the IP address must resolve to 
this name. 
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30.2.8 Understanding the Authentication Process of Access 
Gateway Service 


When a user requests access to a protected resource, the request can be in one of the following 
states: 

+ No session or cookie is established, because this is the user’s first request. 

+ The user’s session is a public session because only public resources have been accessed. 


+ A session is established, the user is authenticated, and the requested resource is from the same 
cookie domain and uses the same contract. 


+ A session is established, the user is authenticated, and the requested resource is from the same 
cookie domain but uses a different contract or the contract has expired. 


+ A session is established, the user is authenticated, but the request does not’ have a session 
cookie because the resource is on a different cookie domain. 


+ A session no longer exists or does not’ exist on the proxy servicing the request. 


Access Gateway Service must handle these conditions and others as it determines whether it needs 
to forward a login request to the Embedded Service Provider or use the user’s existing authentication 
credentials. The following flow charts take you through this process: 

¢ Figure 30-4, “Identifying the Requester,” on page 1184 

+ Figure 30-5, “Determining the Type of Request,” on page 1185 

¢ Figure 30-6, “Determining the Protection Type Assigned to the Resource,” on page 1187 

¢ Figure 30-7, “Evaluating the Cookie Domain,” on page 1188 
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Figure 30-4 Identifying the Requester 
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These first steps determine whether Access Gateway knows the user that has submitted the request. 
In decision point 1, Access Gateway checks for a session cookie in the request. 


+ Ifthe request contains a session cookie, the session cookie needs to be validated. Processing 
continues with the task in decision point 2. 


+ Ifthe request does not contain a session cookie, the user is unknown and is assigned as a public 
user. Access Gateway continues processing with the tasks outlined in Figure 30-5 on page 1185. 


Troubleshooting 


When the request contains a session cookie, Access Gateway checks its local user store for a user 
that matches the session cookie. Each Access Gateway in the cluster maintains its own list of known 
users. 


+ If the session cookie matches one of the locally known users, the user is assigned that identity. 
Access Gateway continues with the tasks outlined in Figure 30-5 on page 1185. 


+ If the session cookie does not’ match one of the locally known users, Access Gateway needs to 
know if one of the other Access Gateways in the cluster knows the user. Processing continues 
with the task in decision point 3. 


Access Gateway queries the session broker to see if one of the other Access Gateways in the cluster 
knows this user. 


¢ Ifa match is found, the user is assigned that identity. Access Gateway continues with tasks 
outlined in Figure 30-5 on page 1185. 


¢ Ifa match is not found, the user is unknown and is assigned as a public user. Access Gateway 
continues with the tasks outlined in Figure 30-5 on page 1185. 


Figure 30-5 Determining the Type of Request 
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Access Gateway examines the request to determine what type of request it is. 
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If the request is a cookie broker reply, Access Gateway strips the cookie from the URL and redirects 
the request to the URL. The redirect is handled as a new request, and this new request flows to the 
task in decision point 6, where the URL is examined. 


If the request is not’ a cookie broker reply, Access Gateway examines the request to see if it is a 
cookie broker request. If it is a cookie broker request, Access Gateway determines whether the user 
is authenticated with the contract required by the protected resource. 


+ Ifthe user is authenticated, Access Gateway creates a cookie broker reply. This reply is handled 
as a new request, and flows to the task in decision point 4. 


+ If the user is not authenticated, the request is redirected to the Embedded Service Provider 
(ESP). The ESP interacts with Identity Server to authenticate the user. Identity Server, the ESP, 
and the reverse proxy all maintain authentication information. The ESP returns a new request, 
which flows to the task in decision point 6, where the URL is examined. 


If the URL does not match a URL of a protected resource (PR), Access Gateway returns an HTTP 
403 error to the user. 


If the URL in the request matches a URL of a protected resource, Access Gateway needs to examine 
the protection type assigned to the resource. Access Gateway continues with the tasks outlined in 
Figure 30-6 on page 1187. 
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Figure 30-6 Determining the Protection Type Assigned to the Resource 
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You configure a protected resource as a public resource when an authentication procedure/contract 
is not assigned to the protected resource. In decision point 7, Access Gateway checks to see if a 
contract has been assigned to the protected resource. 


+ Ifthe protected resource has not been assigned a contract, Access Gateway is finished with its 
authentication checks and continues with policy evaluation. 

+ Ifthe protected resource has been assigned a contract, Access Gateway continues with the task 
in decision point 8. 


For a user to gain access to a resource protected by a contract, the user must have authenticated 
with that contract, or if the contract is configured for it, the user can authenticate with another contract 
as long as the contract is of a equal or higher level. 


+ Ifthe user is authenticated with the required contract, Access Gateway is finished with its 
authentication checks and continues with policy evaluation. 


+ Ifthe user is not authenticated with the required contract, Access Gateway continues with the 
task in decision point 9. 
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Before the user is prompted for credentials, Access Gateway needs to know whether the protected 
resource has been enabled for non-redirected login (NRL). 


+ Ifthe resource has not been configured for non-redirected login, Access Gateway continues with 
the tasks outlined in Figure 30-7 on page 1188. 

+ |f the resource has been configured for non-redirected login, Access Gateway needs to examine 
the request for an authentication header and determine whether the header is valid. Processing 
continues with the tasks outlined in decision points 9a, 9b, and 9c. 


If the request does not contain an authentication header, Access Gateway needs to determine how 
non-redirected login has been configured. On the Authentication Procedure configuration page, you 
can select to enable the Redirect to Identity Server When No Authentication Header Is Provided 
option. 


¢ If this option is enabled, Access Gateway continues with the tasks outlined in Figure 30-7 on 
page 1188. 
¢ If this option is disabled, Access Gateway returns an HTTP 401 unauthorized message. 


If the request does contain an authentication header, Access Gateway must verify that the credentials 
are valid. 


¢ Ifthe authentication credentials are valid, Access Gateway is finished with its authentication 
checks and continues with evaluating the protected resource for policies. 

+ If the authentication credentials are not valid, the process is the same as if the request did not 
contain an authentication header and continues with the task in decision point 9c. 


Figure 30-7 Evaluating the Cookie Domain 
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If you have configured your Access Gateway to use multiple domain-based proxy services, you can 
configure them to share the same cookie domain (domains of development .novell.com and 
support .novell.com can share the cookie domain of novell.com) or configure them so that they 
cannot share a cookie domain (domains of a.slc.com and b.provo.com cannot share a cookie 
domain). 
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When Access Gateway reaches the task in decision point 10, it has determined that the protected 
resource requires a contract and that user is not authenticated with that contract. 


+ 


+ 


If the protected resource is in the same cookie domain, Access Gateway redirects the request to 
the Embedded Service Provider (ESP). The ESP interacts with Identity Server to authenticate 
the user. The ESP returns a new request, which flows to the task in decision point 6, where the 
URL is examined. 


If the protected resource is in a different cookie domain, Access Gateway generates a cookie 
broker request. This new request flows to the task in decision point 5. 


Enabling Caching of Audit Events for Apache Gateway 
Service 


Access Gateway sends audit events to the Audit Server through Platform Agent. You can enable the 
caching of events on Platform Agent. If the Audit Server goes down, Platform Agent will cache all 
audit events triggered during that period and send these to Audit Server when the Audit Server is up. 
Enabling caching prevents any loss of event data. 


NOTE: Platform Agent and Novell Audit are no longer supported. A new Access Manager 4.2 
installation no longer installs Platform Agent and Novell Audit for auditing. If you upgrade from an 
older version of Access Manager to 4.2, Platform Agent is still available. It is recommended to use 
Syslog for auditing. 


1 


Open the 10g4j .xml.base file. 
Windows: C:\Program File\Novell\amlogging\config\log4j.base.xm 
Linux: /etc/opt/novell/amlogging/config/log4j.xml.base 


Look for Audit Server entry. By default the EnableCaching value is set to false. The xml entry for 
Audit server looks as below: 


<appender name="AMAuditNSureAuditAppender" 
class="com.novell.nacm. logging. audit .AMNSureAuditAppender'"> 
<param name="AppendMode" value="DIRECT"/> 
<param name="ErrorHandling" value="DISCARD"/> 
<param name="CertificatePath" 
value="/etc/opt/novell/amlogging/certs/amnacert.pem"/> 
<param name="PrivateKeyPath" 
value="/etc/opt/novell/amlogging/certs/amnapkey.pem"/> 
<param name="EnableCaching" value="false"/> 
<param name="ServerCheckInterval" value="4"/> 


<filter class="com.novell.nacm.logging.audit .AMNSureAuditFilter"> 
</filter> 
</appender> 


3 Modify the EnableCaching value from false to true. 


In Administration Console Dashboard, click Devices > Access Gateways > Edit > Auditing. If 
any of the events are enabled, then disable all the events by deselecting them. Click OK twice. 
On Access Gateways page, click Update. 
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30.2.11 


30.2.12 


30.2.13 


Issue While Accelerating the Ajax Applications 


If you are accelerating an Ajax application that cannot handle redirect and uses an authentication 
contract of 5 or 10 min, then increase the contract time out. Ensure that your Ajax application 
refreshes at an interval of 2 or 5 min. As a best practice, ensure that the Ajax application refresh 
interval is less than 2/3 of the contract time out. 


Accessing Lotus-iNotes through Access Gateway Asks for 
Authentication 


This issue in not related to Access Manager. You need to configure authentication in Lotus-iNotes. 


For more information about configuring Lotus-iNotes, see section Authentication (http:// 
www.redbooks.ibm.com/redbooks/pdfs/sg246518.pdf) in the iNotes Web Access Deployment and 
Administration guide. 


Configuration Issues 


If you get pending configuration issues when you apply changes on the device, one of the reasons 
could be that the soft link for the certs folder does not exist. 


Enter the following command to check if the soft link exists for the certs folder: 
ls -ltrh /opt/novell/apache2/ 
The following output is displayed: 


lrwxrwxrwx 1 root root 34 2012-03-09 19:43 certs -> /etc/opt/novell/apache2/conf/ 
certs 


If the soft link does not exist, perform the following steps: 


1 Enter the following command: 
ln -sf /etc/opt/novell/apache2/conf/certs opt/novell/apache2/conf/certs 
2 Click Troubleshooting > Certificates. 


3 Select the store that is reporting errors, then click Re-push certificates. You can select multiple 
stores at the same time. 


4 (Optional) To verify that the re-push of the certificates was successful, click Security > 
Command 


The Embedded Service Provider Does not Start 


After importing Access Gateway, sometimes the embedded service provider (ESP) does not start. In 
this case, you will see an error in Administration Console while configuring the ESP: 


Configuration not found 


To workaround this issue, restart the ESP by using the /etc/init.d/novell-mag restart OR 
rcnovell-mag restart command. 
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30.2.14 


30.2.15 


30.2.16 


30.2.17 


Cannot Inject a Photo into HTTP Headers 


You can use the jpegPhoto LDAP attribute to store your photo in JPEG format. This LDAP attribute is 
not injecting the image into a custom HTTP header and returns a 400 Bad Request error. 


Edit the index.php file and add the following line: 


<img src="data: image/jpeg; base64,/9]/4....Base64 value got from 
customheader....... "/> 


Reimporting Access Gateway Takes the IP Address of the 
Old Administration Console 


On Windows, the old Administration Console’s IP address remains in registry after reimporting 
Access Gateway. 


When you reimport Access Gateway to another Administration Console and later upgrade Access 
Gateway, it takes the IP address of the old Administration Console instead of the IP address of the 
new Administration Console. 


Go to the Windows Registry Editor and edit Administration Console value for the following key: 
HKEY_LOCAL_MACHINE\SOFTWARE \Novell\AccessManager \AccessGateway 


Reimporting Access Gateway Service Fails on Windows 
2012 R2 Server 


To fix this issue, perform the following steps: 


1 Uninstall Access Gateway Service. 
2 Ensure the following: 


+ The required ports are open in firewall for communication between Administration Console 
and Access Gateway. 


¢ Antivirus is disabled during installation of Access Gateway. 
+ The time is in sync with Administration Console. 
3 Reinstall Access Gateway Service. 


Access Gateway Caching Issues 


If you have caching issues with inodes, disk space, and cache corruption in Access Gateway, use 
Apache htcacheclean tool which is used to keep the size of mod_disk_cache's storage within a 
certain limit. This tool can run either manually or in daemon mode. When running in daemon mode, it 
sleeps in the background and checks the cache directories at regular intervals for cached content to 
be removed. 


The htcacheclean utility tool is located at: 

Linux: /opt/novell/apache2/sbin 

Windows: C:\Program Files\Novell\apache\bin 
The default cache location is: 


Linux: /var/cache/novell-apache2 
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Windows: C:\apache_cache_root 

Example: To clear 1024 MBytes of cache, run the following command: 
Linux: ./htcacheclean -v -t -p/var/cache/novell-apache2 -11024M 
Windows: htcacheclean.exe -v -t -pC:\apache_cache_root -11024™M 


For more information about Apache htcacheclean tool, see htcacheclean - Clean up the disk cache 
(https://httpd.apache.org/docs/2.2/programs/htcacheclean.html). 


30.2.18 Issues while Changing Management IP Address in Access 
Gateway Appliance 


If Access Gateway Appliance has two NICs, a public and a private, it is unable to change the 
Management IP address of Access Gateway Appliance to a new value. Administration Console 
connects to the changed IP address, but also tries to connect to the old IP address. The following 
procedure allows you to change the IP address manually: 

Stop the AG service /etc/init.d/novell-mag stop 

Stop the JCC service by using the /etc/init.d/novell-jcc stop command. 

Change the IP address in /opt/novell/devman/jcc/conf/settings. properties file. 


Bh WN PF 


Change the IP address in /opt/novell/nam/mag/webapps/agm/WEB- INF/config/current/ 
config. xml file. 


5 Change the IP address in /etc/opt/novell/apache2/conf/listen.conf file. 

6 Using YaST, change the network IP address. 

7 In Administration Console Edir, edit and change the IP address in the following attributes: 
+ Fora specific Access Gateway device entry: 


1. romaAGDeviceXMLDoc of ou=ag-xxxxxx, ou=AppliancesContainer, ou=Partition, 
ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, o=novell 


2. romaAGDeviceSAXMLDoc of ou=ag-xxxxxx, ou=AppliancesContainer, ou=Partition, 
ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, o=novell 
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3. romaAGConfigurationXMLDoc of ou=WorkingConfig, ou=ag-xxxx, 
ou=AppliancesContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_ Root, 
ou=accessManagerContainer, o=novell 


4. romaAGConfigurationXMLDoc of ou=CurrentConfig ou=ag-xxxx, 
ou=AppliancesContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_ Root, 
ou=accessManagerContainer, o=novell 


+ For the specific Access Gateway (esp)-identity server entry: 


1. romalDPDeviceSAXMLDoc of ou=idp-esp-xxxxxx, ou=AppliancesContainer, 
ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, 
o=novell 


2. romalDPDeviceXMLDoc of ou=idp-esp-xxxxxx, ou=AppliancesContainer, ou=Partition, 
ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, o=novell 


+ For other Access Gateway device entry (if they are in a cluster): 


1. romaAGConfigurationXMLDoc of ou=WorkingConfig, ou=ag-yyyy, 
ou=AppliancesContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_ Root, 
ou=accessManagerContainer, o=novell 


2. romaAGConfigurationXMLDoc of ou=CurrentConfig, ou=ag-yyyy, 
ou=AppliancesContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_ Root, 
ou=accessManagerContainer, o=novell 


+ For tmp folder entry: 


1. romaAGConfigurationXMLDoc of ou=CurrentConfig, ou=tmp_zzz, 
ou=AppliancesContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_ Root, 
ou=accessManagerContainer, o=novell 


2. romaAGConfigurationXMLDoc of ou=WorkingConfig, ou=tmp_zzz, 
ou=AppliancesContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_ Root, 
ou=accessManagerContainer, o=novell 


8 Start Access Gateway service by using the /etc/init.d/novell-mag start command. 
9 Start the JCC service by using the /etc/init.d/novell-jcc start command. 
10 Restart Administration Console, Identity Server and other Access Gateways in cluster. 


30.2.19 Issue While Adding Access Gateway in a Cluster 


You may get the following error while adding Access Gateway in a cluster: 
Unable to read keystore: /opt/novell/devman/jcc/certs/esp/4 CO6FOAE2EFAED18/signing.keystore 
To workaround this issue: 


1 Click Troubleshooting > Certificates. 
2 Select the store that is reporting errors, then click Re-push certificates. 
You can select multiple stores at the same time. 


3 (Optional) To verify that the re-push of the certificates was successful, click Security > 
Command Status. 
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30.2.20 


30.3 


Access Gateway Fails to Start After Upgrading SLES 11 SP3 
to SLES 12 


If you upgrade the operating system for all devices from SLES 11 SP3 to SLES 12, Access Gateway 
fails to start. The following error message is displayed: 


/opt/novell/apache2/sbin/httpd: error while loading shared libraries: 
libpcrc.so.0: wrong ELF class: ELFCLASS32 


This happens because Access Gateway dependencies do not get copied during an operating system 
upgrade. 


Workaround: Reinstall Access Gateway or create the following symbolic links at Access Gateway 
server: 


ln -s /usr/1ib64/libpcre.so.1.2.1 /usr/1ib64/libpcre.so.0 
in -s /usr/1ib64/libdb-4.8.so /usr/lib64/libdb-4.5.so 

in -s /usr/1ib64/libodbc.so.2.0.0 /usr/lib64/libodbc.so.1 
ln -s /usr/1ib64/libesmtp.so.6 /usr/1ib64/libesmtp.so.5 


Troubleshooting Identity Server and 
Authentication 


This section provides information about the following topics: 


¢ Section 30.3.1, “Useful Networking Tools for Linux Identity Server,” on page 1195 


¢ Section 30.3.2, “Troubleshooting 100101043 and 100101044 Liberty Metadata Load Errors,” on 
page 1196 


¢ Section 30.3.3, “Authentication Issues,” on page 1203 


¢ Section 30.3.4, “Problems Reading Keystores after Identity Server Re-installation,” on 
page 1206 


¢ Section 30.3.5, “After Setting Up the User Store to Use SecretStore, Users Report 500 Errors,” 
on page 1206 


¢ Section 30.3.6, “When Multiple Browser Logout Option Is Enabled, User Is Not Getting Logged 
Out from Different Sessions,” on page 1207 


¢ Section 30.3.7, “After Consuming a SAML Response, the Browser Is redirected to an Incorrect 
URL,” on page 1207 


¢ Section 30.3.8, “Configuring SAML 1.1 Identity Provider Without Specifying Port in the Login 
URL Field,” on page 1207 


¢ Section 30.3.9, “Attributes Are Not Available Through Form Fill When OIOSAML Is Enabled,” on 
page 1207 


¢ Section 30.3.10, “Issue in Importing Metadata While Configuring Identity Provider or Service 
Provider Using Metadata URL,” on page 1208 


¢ Section 30.3.11, “Enabling Secure or HTTPOnly Flags for Cluster Cookies,” on page 1208 


¢ Section 30.3.12, “Apache Portable Runtime Native Library Does Not Get Loaded in Tomcat,” on 
page 1208 


¢ Section 30.3.13, “Metadata Mentions Triple Des As Encryption Method,” on page 1210 


¢ Section 30.3.14, “Issue in Accessing Protected Resources with External Identity Provider When 
Both Providers Use Same Cookie Domain,” on page 1210 
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+ Section 30.3.15, “SAML Intersite Transfer URL Setup Does Not Work for Non-brokered Setups 
after Enabling SP Brokering,” on page 1210 


¢ Section 30.3.16, “Orphaned Identity Objects,” on page 1211 


¢ Section 30.3.17, “Users cannot Log In to Identity Server When They Access Protected 
Resources with any Contract Assigned,” on page 1211 


¢ Section 30.3.18, “Attribute Query from OIOSAML.SP Java Service Provider Fails with Null 
Pointer,” on page 1212 


¢ Section 30.3.19, “Disabling the Certificate Revocation List Checking,” on page 1212 


¢ Section 30.3.20, “Step up Authentication for Identity Server Initiated SSO to External Provider 
Does Not Work Unless It has a Matching Local Contract,” on page 1212 


¢ Section 30.3.21, “Metadata Cannot be Retrieved from the URL,” on page 1212 
¢ Section 30.3.22, “Requesting the Authentication to a Service Provider Fails,” on page 1212 


¢ Section 30.3.23, “SAML 2.0 POST Compression Failure Does not Throw a Specific Error Code,” 
on page 1213 


¢ Section 30.3.24, “SAML 1.1 Service Provider Re-requests for Authentication,” on page 1213 


¢ Section 30.3.25, “Issue in Generating WS-Federation Claim for SharePoint 2010 On Windows,” 
on page 1213 


¢ Section 30.3.26, “Identity Server Statistics Logs Do Not Get Written In Less Than One Minute,” 
on page 1214 


¢ Section 30.3.27, “No Error Message Is Written in the Log File When an Expired Certificate Is 
Used for the X509 Authentication,” on page 1214 


¢ Section 30.3.28, “Terminating an Existing Authenticated User from Identity Server,” on 
page 1214 


¢ Section 30.3.29, “Clustered Nodes Looping Due to JGroup Issues,” on page 1215 
¢ Section 30.3.30, “Authentication With Aliases Fails,” on page 1215 
¢ Section 30.3.31, “nidp/app Does Not Redirect to nidp/portal after Authentication,” on page 1216 


¢ Section 30.3.32, “Login to Office 365 Fails when WS-Trust MEX Metadata Is Larger than 65 KB,” 
on page 1216 


¢ Section 30.3.33, “Unsafe Server Certificate Change in SSL/TLS Renegotiations Is Not Allowed,” 
on page 1216 


¢ Section 30.3.34, “Viewing Request and Response Headers of All Protocols in a Log File,” on 
page 1217 


For information about Identity Server logging, see Section 21.3.1, “Configuring Logging for Identity 
Server,” on page 1038 and Section 21.3.2, “Configuring Session-Based Logging,” on page 1040. 


30.3.1 Useful Networking Tools for Linux Identity Server 


You can use the following tools (Linux and open source) to troubleshoot network problems: 
¢ netstat: Displays information related to open ports on your server. Lets you view listeners and 
various IP addresses, such as the TCP output state. 


¢ iptables: Allows you to change the default ports (8080 and 8443) to the standard ports (80 and 
443) for HTTP traffic. 


+ netcat: A networking utility that reads and writes data across network connections, using the 
TCP/IP protocol. Netcat is useful for checking connectivity with the user store. 
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30.3.2.1 


+ Idapsearch: An LDAP search tool useful for Administration Console and Identity Server. For 
example, you can generate an LDAP search/bind matching what Identity Server sends, to 
confirm whether an issue is with Identity Server JAR files. 


+ tcpdump: A command line tool for monitoring network traffic. Captures and displays packet 
headers and matches them against a set of criteria. 


+ LDAP Browser/Editor: Lets you export configuration information to a file, and to confirm that 
Access Manager objects and attribute values are valid in an AccessManagerContainer. A 
number of open source versions are available from the Internet. 


Troubleshooting 100101043 and 100101044 Liberty 
Metadata Load Errors 


Identity Server is the identity provider for other Access Manager components. Access Gateways-has 
Embedded Service Providers. When a device is imported into Administration Console and an Identity 
Server configuration is selected for them, a trusted relationship is established with Identity Server by 
using test certificates. When you change these certificates or change from using HTTP to HTTPS, 
you need to ensure that the trusted relationship is reestablished. Metadata is used for establishing 
trusted relationships. 


The metadata exchanged between service providers and identity providers contains public key 
certificates, key descriptors for message signing, a URL for the SSO service, a URL for the SLO 
(single logout) service, and so on. With Access Manager, this metadata is accessible on both Identity 
Server and the Embedded Service Provider of the device. Errors are generated when either the 
identity provider could not load the service provider's metadata (100101043), or the service provider 
could not load the metadata of the identity provider (100101044). 


If users are receiving either of these errors when they attempt to log in, verify the following: 


+ “The Metadata” on page 1196 
+ “DNS Name Resolution” on page 1197 
¢ “Certificate Names” on page 1198 


¢ “Certificates in the Required Trust Stores” on page 1199 
If these steps do not solve your problem, try the following: 
+ “Enabling Debug Logging” on page 1201 
+ “Testing Whether the Provider Can Access the Metadata” on page 1203 


e “Manually Creating Any Auto-Generated Certificates” on page 1203 


+ For information about metadata validation process and the flow of events that occur when 
accessing a protected resource on Access Gateway, see “Troubleshooting 100101043 and 
100101044 Errors in Access Manager” (http://www.novell.com/coolsolutions/appnote/ 
19456.html). 


The Metadata 


If you change the base URL of the Identity Provider, all service providers, including Embedded 
Service Providers, need to be updated so that they use the new metadata: 


+ “Embedded Service Provider Metadata” on page 1197 
¢ “Service Provider Metadata” on page 1197 
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Embedded Service Provider Metadata 


If you change the base URL of the Identity Provider, all Access Manager devices that have an 
Embedded Service Provider need to be updated so that new metadata is imported. To force a re- 
import of the metadata, you need to configure the device so it does not’ have a trusted relationship 
with Identity Server, update the device, reconfigure the device for a trusted relationship, then update 
the device. The following steps explain how to force Access Gateway to re-import the metadata of 
Identity Server. 


1 In Administration Console Dashboard, click Devices > Access Gateways > Edit > Reverse 
Proxies/Authentication. 

2 Select None for the Identity Server Cluster option, click OK twice, then update Access Gateway. 

3 Click Edit > Reverse Proxies/Authentication. 


4 Select an Identity Server configuration for the Identity Server Cluster option, click OK twice, then 
update Access Gateway. 


Service Provider Metadata 


If you have set up federation with another provider over the Liberty, SAML 1.1, SAML 2.0, or WS 
Federation protocol and you change the base URL of Identity Server, you need to update the provider 
with the new metadata to reestablish the trusted relationship. If the provider is another Identity Server, 
follow the procedure below to update the metadata; otherwise, follow the provider’s procedures. 


1 In Administration Console Dashboard, click Devices > Identity Servers > Edit > [Protocol] > 
[Provider] > Metadata. 

2 Click Reimport. 

3 Follow the steps in the wizard. 
For more information, see Section 3.9.7, “Managing Metadata,” on page 189. 


DNS Name Resolution 


When the service provider tries to access the metadata on the identity provider, it sends the request 
to the hostname defined in the base URL configuration of Identity Server. The base URL in Identity 
Server configuration is used to build all the metadata end points. 


To view the metadata of Identity Server with a DNS name of idpcluster.1lab.novell.com, enter 
the following URL: 


https://idpcluster.lab.novell.com:8443/nidp/idff/metadata 


Scan through the document and notice the multiple references to https: // 
idpcluster.lab.novell.com/... You should see lines similar to the following: 


<md : SoapEndpoint> 
https://idpcluster .lab.novell.com:8443/nidp/idff/soap 
</md : SoapEndpoint> 


<md:SingleLogoutServiceURL> 
https://idpcluster.lab.novell.com:8443/nidp/idff/slo 
</md:SingleLogoutServiceURL> 


<md:SingleLogoutServiceReturnURL> 


https://idpcluster.lab.novell.com:8443/nidp/idff/slo_return 
</md:SingleLogoutServiceReturnURL> 
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30.3.2.3 


The Embedded Service Provider of Access Gateway must be able to resolve the 
idpcluster.lab.novell.com hostname of Identity Server. To test that it is resolvable, send a ping 
command with the hostname of Identity Server. For example, from Access Gateway: 


ping idpcluster.lab.novell.com 


The same is true for Identity Server. It must be able to resolve the hostname of Access Gateway. To 
discover the URL for Access Gateway metadata: 


1 In Administration Console Dashboard, click Devices > Access Gateways > Edit > Reverse 
Proxy/Authentication. 
2 View the Embedded Service Provider section. 
The URL of the metadata is displayed in this section. 
To view the metadata, enter the displayed URL. Scan through the document and notice the multiple 


references to the hostname of Access Gateway. You should see lines similar to the following. In these 
lines, the hostname is ag1.provo.novell.com. 


<md : SoapEndpoint> 
http://ag1.provo.novell.com:80/nesp/idff/spsoap 
</md : SoapEndpoint> 


<md:SingleLogoutServiceURL> 
http://ag1.provo.novell.com:80/nesp/idff/spslo 
</md:SingleLogoutServiceURL> 


<md:SingleLogoutServiceReturnURL> 
http://ag1.provo.novell.com:80/nesp/idff/spslo_return 
</md:SingleLogoutServiceReturnURL> 


To test that Identity Server can resolve the hostname of Access Gateway, send a ping command with 
the hostname of Access Gateway. For example, from Identity Server: 


ping ag1.provo.novell.com 


To view sample log entries that are logged when a DNS name cannot be resolved, see “The 
Embedded Service Provider Cannot Resolve the Base URL of Identity Server” on page 1201. 


Certificate Names 


Ensure that the certificates for Identity Server and the Embedded Service Provider match the 
hostnames defined in the metadata URL (see “DNS Name Resolution” on page 1197). 


When Identity Server and Access Gateway are enabled for HTTPS, all communication to these 
devices requires that the devices send back a server certificate. Not only must the certificate be 
assigned to the appropriate device, but the subject name of the device certificate must match the 
hostname of the device it is assigned to. 


To verify the certificate name of Identity Server certificate: 


1 In Administration Console Dashboard, click Devices > Identity Servers > Edit. 
2 Click the SSL Certificate icon. 
The SSL Connector keystore is displayed 
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3 Verify that the subject name of the certificate matches the DNS name of Identity Server. 
+ Ifthe names match, a certificate name mismatch is not causing your problem. 


+ Ifthe names do not match, you need to either create a certificate that matches or import one 
that matches. For information about how to create a certificate for Identity Server, see 
Chapter 17, “Enabling SSL Communication,” on page 977. 


To verify the certificate name of Access Gateway certificate: 


1 In Administration Console Dashboard, click Devices > Access Gateways > Edit > [Name of 
Reverse Proxy]. 


2 Read the alias name of the server certificate, then click the Server Certificate icon. 


3 Verify that the Subject name of the server certificate matches the published DNS name of the 
proxy service of Access Gateway. 


+ Ifthe names match, a certificate name mismatch is not causing your problem. 


+ Ifthe names do not match, you need to either create a certificate that matches or import one 
that matches. For information about how to create an Access Gateways certificate, see 
“Configuring Access Gateway for SSL” on page 980. 


To view sample log entries that are logged to the catalina. out file when the certificate has an 
invalid name, see “The Server Certificate Has an Invalid Subject Name” on page 1202. 


Certificates in the Required Trust Stores 


Ensure that the issuers of Identity Server and Embedded Service Provider certificates are added to 
the appropriate trusted root containers. 


When the server certificates are sent from the identity provider to the service provider client, and from 
the service provider to the identity provider client, the client needs to be able to validate the 
certificates. Part of the validation process is to confirm that the server certificate has been signed by a 
trusted source. By default, well known external trusted certificates are bundled with Access Manager. 
You can view this list here: Administration Console > Security > Certificates > External Trusted 
Roots. If the issuer of server certificate is not present in the External Trusted Root list, the import the 
issuers of the server certificate (intermediate and trusted roots) into the correct trusted root stores: 


+ The intermediate and trusted roots of the Embedded Service Provider certificate must be 
imported into the NIDP Trust Store. 


+ The intermediate and trusted roots of Identity Server certificate must be imported into the ESP 
Trust Store. 
For more information, see Section 13.5, “Importing a Signed Certificate,” on page 953. 


If you use certificates generated by Administration Console CA, the trusted root certificate is the 
same for Identity Server and the Embedded Service Provider. If you are using external certificates, 
the trusted root certificate might not be the same, and there might be intermediate certificates that 
need to be imported. 
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To verify the trusted root certificates: 


1 In Administration Console Dashboard, click Security > Certificates. 


2 Determine the issuer of Identity Server certificate and the Embedded Service Provider 
certificate: 


2a Click the name of Identity Server certificate, note the name of the Issuer, then click Close. 


2b Click the name of the Embedded Service Provider certificate of Access Gateway, note the 
name of the Issuer, then click Close. 


2c (Conditional) If you do not know the names of these certificates, see “Certificate Names” on 
page 1198. 


3 To verify the trusted root for Identity Server, click Devices> Identity Servers > Edit > Security > 
NIDP Trust Store. 


4 inthe Trusted Roots section, scan for a certificate subject that matches the issuer of the 
Embedded Service Provider certificate, then click its name. 


+ Ifthe Issuer has the same name as the Subject name, then this certificate is the root 
certificate. 


+ If the Issuer has a different name than the Subject name, the certificate is an intermediate 
certificate in the chain. Click Close, and ensure that another certificate in the trust store is 
the root certificate. If it isn’t there, you need to import it and any other intermediate 
certificates between the one you have and the root certificate. 


5 To verify the trusted root for the Embedded Service Provider, click Devices > Access Gateways 
> Edit >Service Provider Certificates> Trusted Roots. 


6 In the Trusted Roots section, scan for a certificate subject that matches the issuer of Identity 
Server certificate, then click its name. 


+ Ifthe Issuer has the same name as the Subject name, then this certificate is the root 
certificate. 


+ Ifthe Issuer has a different name than the Subject name, the certificate is an intermediate 
certificate in the chain. Click Close, and ensure that another certificate in the trust store is 
the root certificate. If it isn’t there, you need to import it and any other intermediate 
certificates between the one you have and the root certificate. 


7 (Optional) If you have clustered your Identity Servers and Access Gateways and you are 
concerned that not all members of the cluster are using the correct trusted root certificates, you 
can re-push the certificates to the cluster members. 


7a Click Troubleshooting > Certificates. 


7b Select the Trust Store of your Identity Servers and Access Gateways, then click Re-push 
certificates. 


7c Update the Identity Severs and Access Gateways. 


7d Check the command status of each device to ensure that the certificate was pushed to the 
device. From Identity Servers page or Access Gateways page, click the Commands link. 


To view sample log entries that are logged to the catalina. out file when a trusted root certificate is 
missing, see “Trusted Roots Are Not Imported into the Appropriate Trusted Root Containers” on 
page 1202. 
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30.3.2.5 Enabling Debug Logging 


You can enable Identity Server logging to dump more verbose Liberty information to the 
catalina. out file on both Identity Server and the Embedded Service Provider of Access Gateway. 


1 In Administration Console Dashboard, click Devices > Identity Servers > Edit > Auditing and 
Logging. 

Select Enabled for File Logging and Echo to Console. 

In the Component File Logger Levels section, set Application and Liberty to a debug level. 
Click OK, update Identity Server, then update Access Gateway. 
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After enabling and applying the changes, duplicate the issue to add specific details to the log file 
for the issue. 


If the error is the 100101044 error, look at the log file on the Embedded Service Provider for the 
error code 


If the error is the 100101043 error, look at the log file on Identity Server for the error code. 
On Linux, look at the catalina. out file, and on Windows, look at the stdout . log file. 


6 (Conditional) To view the log files from Administration Console, click Auditing > General 
Logging, then select the file and download it. 


N 


(Conditional) To view the log files on the device, change to the log directory. 
+ On Linux, change to the /var/opt/novell/nam/logs/idp directory. 
+ On Windows Server 2012, change to the /Program Files (x86)/Novell/Tomcat/logs 
directory. 


Below are a few typical entries illustrating the most common problems. They are from the 
catalina. out file of the Embedded Service Provider: 


+ “The Embedded Service Provider Cannot Resolve the Base URL of Identity Server” on 

page 1201 
¢ “Trusted Roots Are Not Imported into the Appropriate Trusted Root Containers” on page 1202 
+ “The Server Certificate Has an Invalid Subject Name” on page 1202 


The Embedded Service Provider Cannot Resolve the Base URL of Identity 
Server 


When the Embedded Service Provider cannot resolve the DNS name of Identity Server, the metadata 
cannot be loaded and a hostname error is logged. In the following entries, the Embedded Service 
Provider cannot resolve the idpcluster.lab.novell.com name of Identity Server. 
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<amLogEntry> 2009-08-061T16:24:56Z INFO NIDS Application: AM#500105024: 
AMDEVICEID#esp-09C720981EEE4EB4: AMAUTHID#2CA1168DF7343A42C7879 
E707C51A03C: ESP is requesting metadata from IDP https:// 
idpcluster.lab.novell.com/nidp/idff/metadata </amLogEntry> 


<amLogEntry> 2009-08-06T16:24:56Z SEVERE NIDS IDFF: AM#100106001: 
AMDEVICEID#esp-09C720981EEE4EB4: Unable to load metadata for Embedded 

Service Provider: https://idpcluster.lab.novell.com/nidp/idff/ 

metadata, error: AM#300101046: AMDEVICEID#esp-09C720981EEE4EB4: : Attempted to 
connect to a url with an unresolvable host name 

</amLogEntry> 


<amLogEntry> 2009-08-061T16:24:56Z INFO NIDS Application: AM#500105039: 
AMDEVICEID#esp-09C720981EEE4EB4: AMAUTHID#2CA1168DF7343A42C7879 
E707C51A03C: Error on session id 2CA1168DF7343A42C7879E707C51A03C, 
error 100101044-esp-09C720981EEE4EB4, Unable to authenticate. 
AM#100101044: AMDEVICEID#esp-09C720981EEE4EB4:: Embedded Provider 
failed to load Identity Provider metadata </amLogEntry> 


Trusted Roots Are Not Imported into the Appropriate Trusted Root Containers 


When the trusted roots are not imported into the appropriate trusted root containers, a certificate 
exception is thrown and an untrusted certificate message is logged. In the following log entries, the 
Embedded Service Provider is requesting metadata from Identity Server, but the Embedded Service 
Provider does not trust Identity Server certificate because the trusted root of the issuer of Identity 
Server certificate is not in the Embedded Service Provider’s trusted root container. 


<amLogEntry> 2009-08-05T16:07:53Z INFO NIDS Application: AM#500105024: 
AMDEVICEID#esp-09C720981EEE4EB4: AMAUTHID#D983B08C28D35221D13 9D33E5324F98F: ESP 
is requesting metadata from IDP https://idpcluster.lab.novell.com/nidp/idff/ 
metadata </amLogEntry> 


<amLogEntry> 2009-08-05T16:07:53Z SEVERE NIDS IDFF: AM#100106001: AMDEVICEID#esp- 
09C720981EEE4EB4: Unable to load metadata for Embedded ServiceProvider: https:// 
idpcluster.lab.novell.com/nidp/idff/metadata, error: 
java.security.cert.CertificateException: Untrusted Certificate- chain </ 
amLogEntry> 


<amLogEntry> 2009-08-05T16:07:53Z INFO NIDS Application: AM#500105039: 
AMDEVICEID#esp -09C720981EEE4EB4: AMAUTHID#D983 BO8C28D35221D139 D33E5324F98F: 
Error on session id D983B08C28D35221D139D33E5324F98F, error 100101044-esp- 
09C720981EEE4EB4, Unable to authenticate. AM#100101044: AMDEVICEID#esp- 
09C720981EEE4EB4:: Embedded Provider failed to load Identity Provider metadata </ 
amLogEntry> 


The Server Certificate Has an Invalid Subject Name 


When the certificate has an invalid subject name, the handshake fails. In the log entries below, the 
Embedded Service Provider is requesting metadata from Identity Server. The server certificate name 
does not match, so the Embedded Service Provider is unable to authenticate and get the metadata 
necessary to establish the trusted relationship. 
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<amLogEntry> 2009-07-05T16:07:53Z INFO NIDS Application: AM#500105024: 
AMDEVICEID#esp -09C720981EEE4EB4: AMAUTHID#D983B08C28D35221D139D33 E5324F98F: ESP 
is requesting metadata from IDP 
https://idpcluster.lab.novell.com/nidp/idff/metadata </amLogEntry> 


<amLogEntry> 2009-07-05T16:07:53Z SEVERE NIDS IDFF: AM#100106001: AMDEVICEID#esp- 
09C720981EEE4EB4: Unable to load metadata for Embedded Service Provider: https:// 
idpcluster.lab.novell.com/nidp/idff/metadata, error: Received fatal alert: 
handshake_failure </amLogEntry> 


<amLogEntry> 2009-07-05T16:07:53Z INFO NIDS Application: AM#500105039: 
AMDEVICEID#esp -09C720981EEE4EB4: AMAUTHID#D983B08C28D35221D139D33 E5324F98F: Error 
on session id D983B08C28D35221D139D33E5324F98F, error 100101044-esp-09C720981EEE 
4EB4, Unable to authenticate. AM#100101044: AMDEVICEID#esp-09C720981EEE4EB4: 
Embedded Provider failed to load Identity Provider 

metadata </amLogEntry> 


Testing Whether the Provider Can Access the Metadata 


To test whether the metadata is available for download, enter the metadata URL of the identity 
provider and service provider. If the DNS name of the identity provider is 
idpcluster.lab.novell.com, open a browser at Identity Server and enter the following URL: 


https://idpcluster.lab.novell.com:8443/nidp/idff/metadata 
Open a browser on Access Gateway Service, then enter the same URL. 


Because Access Gateway Appliance does not have a graphical interface, you need to use the curl 

command to test whether Access Gateway Appliance can access the metadata of Identity Server. If 

the DNS name of the identity provider is idpcluster .lab.novell.com, enter the following command 
from Access Gateway machine: 


curl -k https://idpcluster.lab.novell.com:8443/nidp/idff/metadata 


To test whether Identity Server can access the metadata URL of Access Gateway, open a browser on 
Identity Server machine. If the published DNS name of service provider is www. aleris.net, enter the 
following URL: 


https://www.aleris.net/nesp/idff/metadata 


Manually Creating Any Auto-Generated Certificates 


Occasionally, there are issues where the subject name was auto-generated and the entire 
configuration appears to be correct, but the 100101044/100101043 error is still reported. Delete the 
auto-generated certificate and manually re-create the server certificate, making sure that it is added 
to the relevant devices and stores. 


Authentication Issues 


This section discusses the following issues that occur during authentication: 


¢ Section 30.3.3.1, “Authentication Classes and Duplicate Common Names,” on page 1204 
¢ Section 30.3.3.2, “General Authentication Troubleshooting Tips,” on page 1204 

¢ Section 30.3.3.3, “Slow Authentication,” on page 1205 

¢ Section 30.3.3.4, “Federation Errors,” on page 1205 

¢ Section 30.3.3.5, “Mutual Authentication Troubleshooting Tips,” on page 1205 
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¢ Section 30.3.3.6, “Browser Hangs in an Authentication Redirect,” on page 1206 
¢ Section 30.3.3.7, “Duplicate Set-Cookie Headers,” on page 1206 


30.3.3.1 Authentication Classes and Duplicate Common Names 


If users have the same common name and exist in different containers under the same authentication 
search base, one or more attributes in addition to the common name must be configured for 
authentication to uniquely identify the user. You can set up an authentication class to handle duplicate 
common names. 


1 Select either the name/password or secure name/password class. 


2 Add two properties to the class: 


+ Query: The value of the Query attribute needs to be a valid LDAP query string. Field names 
from the JSP login form can be used in the LDAP query string as variables for LDAP 
attribute values. The variables must be enclosed between two % characters. For example, 
(&(objectclass=person)(cn=%Ecom_User_ID%)(mail=%Ecom_Email%)) queries for an 
object of type person that contained a common name equal to the Ecom_User_ID field from 
the specified JSP form and mail equal to the Ecom_Email field from the same JSP form. 


+ JSP: The JSP property value needs to be the name of a new . jsp file that includes all the 
needed fields for the Query property. The value of this attribute does not include the .jsp 
extension of the file. For example, if you create a new .jsp file named login2.jsp, the 
value of the JSP property is login2. 


For more information about creating custom login pages that prompt for more than 
username and password, see “Customizing Identity Server Login Page” on page 256. 


30.3.3.2 General Authentication Troubleshooting Tips 


+ 


+ 


+ 


Use LAN traces to check requests, responses, and interpacket delay times. 
In the user store logs, confirm that the request arrived. Check for internal errors. 


If you have created an admin user for the user store, ensure that the user has sufficient rights to 
find the users in the specified the search contexts. For more information about the required 
rights, see “Configuring an Admin User for the User Store” on page 364. 


Check the user store health and replica layout. See TID 3066352. 


Ensure that the user exists in the user store and that the user’s context is defined as a search 
context. 


Ensure that the Liberty protocol is enabled if you have configured Access Manager devices to 
use Identity Server for authentication (click Identity Servers > Edit > General Configuration). 


Check the properties of the class and method. For example, the search format on the properties 
must match what you’ve defined on a custom login page. You might be asking for a name/ 
password login, but the method specifies e-mail login criteria. 


Enable authentication logging options (click Identity Servers > Edit > Auditing and Logging). 


Ensure that the authentication contract matches the base URL scheme. For example, check to 
see if SSL is used across all components. 
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30.3.3.3 Slow Authentication 


The following configuration problems can cause slow authentication: 


¢ If authentication is taking up to a minute per user, verify that your DNS server has been enabled 
for reverse lookups. The JNDI module in Identity Server sends out a request to resolve the IP 
address of the LDAP server to a DNS name. If your DNS server is not enabled for reverse 
lookups, it takes 10 seconds for this request to fail before Identity Server can continue with the 
authentication request. 

¢ If your user store resides on SUSE Linux Enterprise Server 10, which installs with a firewall, you 
must open TCP 524. For more information about the ports that must be open when a firewall 
separates the user store from other Access Manager components, see Setting Up Firewalls in 
the NetIQ Access Manager 4.3 Installation and Upgrade Guide. 


+ If your LDAP user store is large, ensure that the search contexts are as specific as possible to 
avoid searching the entire tree for a user. 


30.3.3.4 Federation Errors 


+ Most errors that occur during federation occur because of time synchronization problems 
between servers. Ensure that all of your servers involved with federation have their time 
synchronized within one minute. 


+ When the user denies consent to federate after clicking a Liberty link and logging in at the 
identity provider, the system displays an error page. The user should acknowledge that 
federation consent was denied and return to the service provider login page. This is the 
expected behavior when a user denies consent. 


30.3.3.5 Mutual Authentication Troubleshooting Tips 


+ LAN traces: 
+ Check the SSL handshake and look at trusted root list that was returned. 


+ The client certificate issuer must be in the identity provider certificate store and be applied 
to all the devices in a cluster. 


+ Ensure that the user exists and meets the authentication criteria. As the user store 
administrator, you can search for a subject name (or certificate mapping attributes defined) 
to locate a matching user. 


+ Enable the Show Certificate Errors option on the Attributes page for the X.509 authentication 
class. (Click Identity Servers > Servers > Edit > Local > Classes > [x.509] > Properties.) 
Enabling this option provides detailed error messages on the login browser, rather than generic 
messages. 


+ Ensure that the certificate subject name matches the user you log in with, if you are chaining 
methods. 


+ Use NTRadPing to test installations. 
+ Verify that the correct UDP port 1812 is specified. 


¢ Verify that the RADIUS server can accept requests from Identity Server. This might require the 
NAS-IP-Address attribute along with credentials. 


¢ Verify that the user exists in the user store if multiple methods are added to a contract. 

¢ Verify that user authentication works independent of Access Manager. 

¢ Verify that the NMAS server is local and no tree walks are occurring across the directory. 
+ Ensure that the NUAS_LOGIN SEQUENCE property is defined correctly. 
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30.3.3.6 


30.3.3.7 


30.3.4 


30.3.5 


Browser Hangs in an Authentication Redirect 


If the browser hangs when the user attempts to authenticate at an identity provider, determine 
whether a new authentication contract was created and set as the default contract on Identity Server. 
If this is the case and you have an Access Gateway resource set to accept any contract from the 
identity provider, you should navigate to the Overview tab for the protected resource and specify Any 
again in the Contract drop-down menu. Then click OK, then update Access Gateway. 


Duplicate Set-Cookie Headers 


The Access Manager releases previous to Access Manager 3.1 SP1 allowed a colon in the Set- 
Cookie header. Because the cookie specifications stipulate that a colon character cannot be used ina 
cookie, the Set-Cookie header in Access Manager 3.1 SP1 removes the colon and sets a value 
similar to the following: 


UrnNovellNidpClusterMember Id=~03~0Bs1lo~O0A~OB~14mop~O0C~09; Path=/nidp 


A second Set-Cookie header is included with the colon value to allow for backward compatibility with 
devices that have not been upgraded to Access Manager 3.1 SP1. The devices requiring this old 
style cookie include Identity Servers that haven’t been upgraded and any device with an Embedded 
Service Provider that hasn’t been upgraded. The old Set-Cookie header value looks similar to the 
following: 


urn:novell:nidp:cluster:member : id=~03~0Bslo~0A~OB~14mop~0C~09; Path=/nidp 


Both cookies contain the same information. Setting the two cookies does not impact functionality or 
performance. 


Problems Reading Keystores after Identity Server Re- 
installation 


This can occur if you replace a hard drive and incorrectly reinstall Identity Server. See Uninstalling 
Components in the NetIQ Access Manager 4.3 Installation and Upgrade Guide for the correct 
procedure. 


After Setting Up the User Store to Use SecretStore, Users 
Report 500 Errors 


If your eDirectory user store is running on SLES 11 SP1 64-bit (or a higher version) on x86-64 
hardware, you can install the NMAS SAML method for SecretStore from Administration Console, but 
the eDirectory server is missing the required support libraries. 


When users try to enter values for SecretStore entries in a form, they receive the following message: 
Status: 500 Internal Server Error, Description: Datastore Error 


To correct the problem, you need to install the missing libraries on your eDirectory server. For 
instructions, see TID 7006437 (http://www.novell.com/support/ 
viewContent.do?externalld=7006437 &sliceld=1). 
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30.3.6 When Multiple Browser Logout Option Is Enabled, User Is 
Not Getting Logged Out from Different Sessions 


Allow multiple browser session logout option in Identity Server cluster specifies whether a user with 
more than one session to the server is presented with an option to log out of all sessions. If you do 
not select this option, only the current session can be logged out. If you deselect this option in 
instances where multiple users log in as guests, then when one user logs out, none of the other 
guests are logged out. When you enable this option, you must also restart any Embedded Service 
Providers that use this Identity Server configuration and for logout URL you need to configure it as / 
nidp/app/logout. 


30.3.7 After Consuming a SAML Response, the Browser Is 
redirected to an Incorrect URL 


After consuming a SAML response, 302 redirect to RelayState URL is sent to an Incorrect URL. 
Check whether the relay state is URL encoded. To fix this issue, add the following entry in the 
web. xml file: 


(/opt/novell/nids/lib/webapp/WEB- INF/web.xm1l)<context-param> <param- 
name>decodeRelayStateParam</param-name> <param-value>true</param-value></context - 
param> 


30.3.8 Configuring SAML 1.1 Identity Provider Without Specifying 
Port in the Login URL Field 


While adding the identity provider, do not specify the login URL and clear the show card option. Use 
the login URL to access the service provider: 


https://idp.sitea.novell.com/nidp/saml/idpsend? 
PID = https://idp.siteb.novell.com/nidp/saml/metadata& 
TARGET = https://idp.siteb.novell.com/nidp/app 


In the identity provider, while adding the service provider, configure ID in the intersite transfer page. 
Configure the login URL with port number -2443 instead of the provider ID URL: 


https://idp.sitea.novell.com:2443/nidp/saml/idpsend? 
id = <idname>&TARGET=nhttps://idp.siteb.novell.com:2443/nidp/app 


30.3.9 Attributes Are Not Available Through Form Fill When 
OIOSAML Is Enabled 


To workaround this issue, create a new attribute set with the OIOSAML mandatory attributes having 
remote attribute mapping as its OID equivalent and associate the attribute set to the identity provider 
configured at the SP. 
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30.3.10 


30.3.11 


30.3.12 


Issue in Importing Metadata While Configuring Identity 
Provider or Service Provider Using Metadata URL 


To work around this issue, manually copy the metadata by selecting the metadata text option while 
configuring an identity provider or service provider. The metadata text can be obtained from the 
browser. 


Enabling Secure or HTTPOnly Flags for Cluster Cookies 


By default, Identity Server and ESP cluster cookies do not have any secure or HTTPOnly flags. 
To enable secure or HTTPOnly cookie, perform the following steps: 


1 In Administration Console Dashboard, click Devices > Identity Servers > Edit > Options > New. 
2 Specify the following details: 


Property Type Property Value 
SECURE CLUSTER COOKIE Select true. 
HTTP ONLY CLUSTER Select true. 

3 Click OK. 


4 Restart Tomcat. 


NOTE: The secure cookies cannot be configured for ESP cluster as the communication between 
Access Gateway and NESP is over HTTP on the loopback interface. 


Apache Portable Runtime Native Library Does Not Get 
Loaded in Tomcat 


The Apache Portable Runtime (APR) native library is not enabled by default. To workaround this 
issue, enable the APR native library. 


Steps to enable the APR native library: 


1. Download OpenSSI (http://www.openssl.org/source/). 
2. Extract the source (tar -zxvf openssl-version). 


3. Compile and install (cd openssl-version) using the ./config, ./config shared, make, and 
sudo make install commands. 


For example: 
idp:~/openssl-0.9.8q #./config 
idp:~/openssl-0.9.8q #./config sharedapr-1.4.5 
idp:~/openssl-0.9.8q #make 
idp:~/openssl-0.9.8q #sudo make install 

4. Download APR (http://apr.apache.org/download.cgi). 

5. Extract the source (tar -zxvf apr-version). 
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. Compile and install (cd apr-version) using the ./configure, make, and sudo make install 


commands. 

For example: 

idp:~/apr-apr-1.4.5 #./configure 
idp:~/apr-apr-1.4.5 #make 
idp:~/apr-apr-1.4.5 #sudo make install 


7. Create a lib folder under Openssl-version. For example, idp:~/openssl-0.9.8q/lib # 


8. Copy *.so files from openssl-version to lib using idp:~/openssl-0.9.8q/lib #cp ../*.so. 
9. Extract the wrapper library sources located in the Tomcat binary bundle $CATALINA_ HOME/bin/ 


10. 


11. 


12. 


13. 


14. 


tomcat-native.tar.gz or download the latest version. 


Extract the source, compile, and install $CATALINA_HOME/bin/tomcat-native-1.1.20-src using 
this command: 


$CATALINA_HOME/bin/tomcat-native-1.1.20-src/jni/native# ./configure --with-apr=/apr-version 
folder location from root --with-java-home=/jdk location from -- libdir=/usr/lib/lib64 --prefix=/usr/ 
lib/lib64 --with-ssl=/openssl folder verion from root. 


Example: Idp1:/var/opt/novell/tomcat7/bin/tomcat -native-1.1.20-src/jni/ 
native#./configure --with-apr=/root/apr-1.4.5 --with-java-home=/opt/novell/ 
jdk1.6.0_26/ 


If the message says "checking OpenSSL library version... ok", installation is successful. If it 
shows "checking OpenSSL library version... is not compatible", installation is not successful. 


Tomcat-Native-library compilation and installation: 
idp1:/$CATALINA_HOME/bin/tomcat-native-1.1.20-src/jni/native # make 


idp1:/$CATALINA_HOME/bin/tomcat -native-1.1.20-src/jni/native # sudo make 
install 


Go to idp:/usr/lib/lib64 #. Crate link of these two files using the following command: 
Idp:/usr/lib/1ib64 # sudo ln -s libtcnative-1.dylib libtcnative-1.jnilib 


Copy all files from Idp:$CATALINA_HOME/bin/tomcat-native-1.1.20-src/jni/native/.libs to your 
#Native library path (JAVA_LIB_PATH). 


Idp:/var/opt/novell/tomcat7/bin/tomcat -native-1.1.20-src/jni/native/.libs # cp 
* /opt/novell/1ib64 


If you are running the application through the APR connectors, it needs the SSL certificate file in 
the .pem format. 


To Create SSL Certificate File : 

a. Log in to Administration Console. 

b. Under the Security tab, click Certificates. 

c. Select the certificate, which is configured in your IDP Cluster and click that certificate name. 
Example: Configure a certificate with the name [new_idp] and click new_idp. 

d. Click Export Private/Public KeyPair. 

e. Enter the encryption and decryption password. 

f. Save the file. File is saved as .pfx. 

g. Convert the .pfx format to .pem using https://www.sslshopper.com/ssl-converter.html. 
Certificate file to Convert: Enter the location where you have saved the .pfx file. 
Type of Current Certificate: Select PFX/PKCS#12. 

Type To Convert To: select Standard PEM. 
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Click ConvertCerficate. 
PFX Password: Enter the same password as given in step e and save the file. 


15. If you need to run your Administration Console by using the APR connector, configure the 
following details into server.xml of your Administration Console. (vi /opt/novell/nam/ 
adminconsole/conf/server.xml) 


If you need to run your Identity Provider Server using the APR connector you can configure 
these details into server.xml of your Identity Provider Server. (vi /opt/novell/nam/idp/conf/ 
server.xml) 


16. APR Lifecycle Listener <Listener className="org.apache.catalina.core.AprLifecycleListener" 
SSLEngine="on" /> 


17. APR Connector configuration: 


Example: <Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" 
minSpareThreads="25" maxSpareThreads="75" enableLookups="false" UploadTimeout="true" 
acceptCount="100" scheme="https" secure="true" clientAuth="false" ssIProtocol="TLS" 
SSLEngine="on" SSLCertificateFile="${catalina.home}/tomcatcert.pem" 
SSLCertificateKeyFile="${catalina.home}/tomcatkey.pem" SSLPassword="tomcat" /> Give the 
SSL Certificate File the same name as you entered for the .pem file. 


NOTE: SSLCertificateFile and ssIProtocol are required to run when you are using the APR 
connectors. 


18. Restart tomcat. 


30.3.13 Metadata Mentions Triple Des As Encryption Method 


The OIO SAML metadata has tripledes-cbc and AES128-cbc mentioned as encryption methods. If 
triple des is not required, edit the following related tag in metadata and import the metadata manually. 


Node: <md:EncryptionMethodAlgorithm="http://www.w3.org/2001/04/xmlenc#tripledes- 
cbc"/> 


30.3.14 Issue in Accessing Protected Resources with External 
Identity Provider When Both Providers Use Same Cookie 
Domain 


To workaround this issue, set 'agm.lagmode=false' in /opt/novell/singlebox/mag/webapps/agm/ 
agm.properties. 


30.3.15 SAML Intersite Transfer URL Setup Does Not Work for Non- 
brokered Setups after Enabling SP Brokering 


To workaround this issue: 


¢ Create a brokering group that has local IDP as Identity Provider and SP1 and SP2 as Trusted 
Providers. 


¢ Create brokering rules for the Intersite Transfer URL requests to SP2. All requests to SP1 will be 
allowed. 
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30.3.16 Orphaned Identity Objects 


When a persistent federation is configured or a transient federation with user mapping is configured 
by using Liberty, SAML 1 and SAML 2.0, the federation objects are created in the configuration 
store.When you delete or disable a user object, the objects in the configuration datastore related to 
this specific user become orphaned. These orphaned user profile objects affect the user lookup 
operations and system performances. These objects should be removed manually by using the 
Defed Tool: Federation Entry Management. 


This tool clears all the orphaned federation objects related to Liberty, SAML 1, and SAML 2 from the 
trust and configuration datastore, except for Shared Secret entries. 


NOTE: When the Access Manger setup includes Access Gateway and no persistent or transient 
federations have been configured, these objects are not created. 


Linux: 


1 Change the current working directory to /opt/novell/devman/nam_tools/ from a terminal. 
2 Run this command: 


/opt/novell/java/bin/java -classpath .:./lib/nam_tool.jar:./lib/nidp.jar:./ 
1ib/NAMCommon. jar: ./lib/bcprov-jdki5-140.jar - 
Djava.util.logging.config.file=./conf/logging.properties 
com.novell.nam.tools.defed.DefedTool 


3 The Defed tool will ask either to delete the orphan objects orexit from the tool. Select the option 
to delete the orphan objects. The tool will ask you to provide the IP address, port, user DN, and 
password. 


4 The Defed tool deletes the orphaned federation objects and gives the summary of total number 
of federation entries encountered and number of the federation objects deleted. 


This tool can be used to perform the operation on remote server too. 
Windows: 


1 Goto the C:\Program Files (x86)\Novell\nam_tools folder. 
2 Run this command: 


C:\Program Files (x86)\Novell\nam_tools>java -cp lib/nam_tool.jar;lib/ 
nidp.jar;1lib/NAMCommon. jar;1lib/bcprov-jdk15-140.jar - 
Djava.util.logging.config.file=conf\logging.properties 
com.novell.nam.tools.defed.DefedTool 


3 Provide IP address, port, user DN, and password. 


4 The Defed tool deletes the orphaned federation objects and gives the summary of total number 
of federation entries encountered and number of the federation objects deleted. 


This tool can be used to perform the operation on remote server too. 


30.3.17 Users cannot Log In to Identity Server When They Access 
Protected Resources with any Contract Assigned 


To workaround this issue, ensure that the Show Card option is enabled on the default contract. 
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30.3.18 


30.3.19 


30.3.20 


30.3.21 


30.3.22 


Attribute Query from OIOSAML.SP Java Service Provider 
Fails with Null Pointer 


To workaround this issue: 


1 Enable the OIOSAML compliance with service provider. The OIOSAML attribute set will be 
populated. 


2 By default, the mandatory attributes are listed in the Available list. 


3 Ensure that these mandatory attributes are moved from the Available list to the Send with 
authentication list to avoid the Null Pointer exception with OIOSAML compliance service 
providers. 


Disabling the Certificate Revocation List Checking 


For ADFS 2.0 to work with Access Manger SAML 2.0, you must disable the Certificate Revocation 
List (CRL) checking. 


To disable the CRL checking: 


1 Modify the tomcat7 .conf file of Identity Server located at /opt/novell/nam/idp/conf/ 
tomcat7.conf. 


2 Add this parameterJAVA_OPTS="${JAVA_OPTS} -Dcom.novell.nidp.serverOCSPCRL=false". 
3 Restart Identity Server by using this command: /etc/init.d/novell-idp restart. 


Step up Authentication for Identity Server Initiated SSO to 
External Provider Does Not Work Unless It has a Matching 
Local Contract 


For example, if a service provider is configured for a satisfiable contract that is only satisfiable by an 
external provider, then Intersite transfer service does not work. 


To workaround this issue, ensure that any local contract is associated with the service provider. If not, 
then associate the same. External provider without any local contract is not supported 


Metadata Cannot be Retrieved from the URL 


To workaround this issue, verify the network card configuration for the proper DNS. 


Requesting the Authentication to a Service Provider Fails 


To workaround this issue: 


1 Click Devices > Identity Servers > Edit > SAML 2.0 > [Service Provider] > Authentication 
Response. 


2 Change Artifact to Post in the Binding field. 
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30.3.23 SAML 2.0 POST Compression Failure Does not Throw a 
Specific Error Code 


The POST Compression feature is supported when both the identity provider and service provider 
understand SAML 2 POST deflate and inflate. If the service provider sends a compressed message, 
the identity provider needs to decompress the message and vice-versa. For the Access Manager 
identity server and service provider, the nidpconfig. properties file located in /opt/novell/nam/ 
idp/webapps/nidp/WEBINF/classes needs to be modified to enable the SAML 2.0 POST deflate 
and inflate. 


30.3.24 SAML 1.1 Service Provider Re-requests for Authentication 


SAML 1.1 service provider performs a strict check on the name space of the attributes received in 
assertion. 


To disable this, perform the following steps: 


1 Click Devices > Identity Servers > Edit > Options > New. 

2 Select SAML1X ATTRIBUTE MATCH BY NAME in Property Type. 
3 Select true in Property Value. 

4 Click OK > Apply. 


30.3.25 Issue in Generating WS-Federation Claim for SharePoint 
2010 On Windows 
When Access Manager is installed on Windows 2012 and uses a SharePoint 2010 WS-federation 


service provider to build trust relationship with Identity Server, users get a 500 internal error while 
trying to log in to SharePoint 2010. 


This error occurs because Access Manager does not find the method to generate the SharePoint 
claim after authenticating the user at Identity Server. 


To resolve this issue, perform the following steps: 


Navigate to C:\Program Files (x86)\Novell\Tomcat\bin. 
Open the tomcat 7w file. 
Navigate to the Java tab. 


A WN FP 


Search for the following Java Options placeholder: 
-Djava.endorsed.dirs=C: \PROGRA~2\Novell\Tomcat\common\endorsed 
5 Modify this option as follows: 

-Djava.endorsed.dirs=C: \PROGRA~2\Novell\Tomcat\endorsed 


NOTE: Check for the endorsed folder in Tomcat (Catalina Home). This folder should contain stax- 
api-1.0.1.jar, serializer.jar, xalan.jar, xercesImpl.jar, and xml-apis. jar. 
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30.3.26 


30.3.27 


30.3.28 


Identity Server Statistics Logs Do Not Get Written In Less 
Than One Minute 


Identity Server statistics logs do not get written before one minute even though the time specified is 
less than one minute, for example, 10 seconds. This issue happens only when the time is specified to 
less than one minute. 


Do not specify the time less than one minute. As a best practice, you should not set small period 
because it increases the load on the server and also increases the log file size exponentially. 


No Error Message Is Written in the Log File When an 
Expired Certificate Is Used for the X509 Authentication 


When a user tries to authenticate with an expired client certificate, the authentication fails. The log file 
does not have any information about the expiration of the certificate. Browsers also do not display any 
error message about it. 


To see the logs related to expired certificates, perform the following steps: 


1 Enable the following Java option in tomcat7.conf under /opt/novell/nam/idp/conf/: 
JAVA_OPTS="${JAVA_OPTS} -Djavax.net .debug=ss1, handshake" 
This option enables SSL logs. 

2 Restart Identity Server. 


Terminating an Existing Authenticated User from Identity 
Server 


Access Manager provides the ability for users to single sign on to back end web servers. These back 
end web servers provide a series of protected resources that users can only access when 
authenticated to an Identity Server, and authorized by Access Gateway. Having parsed the user 
credentials, and credentials validated against a back end user store, Identity Server creates and 
maintains an active session for that user. Only when the user manually logs out of Identity Server, or 
if the user’s session timeout expires, then the user’s active session will be removed. If the user 
continuously accesses protected resources before the session timeout expires, the session can 
remain active forever. 


Use case: You may want to terminate an authenticated user sometimes. Some of the cases are listed 
below. 


¢ User A who currently has an active session on Identity Server and access to many protected 
resources, has had a designation change within the organization causing a change to resources 
that may be available. By forcing user A to logout and login again, his new roles or attributes may 
be retrieved by Identity Server and used in policy evaluations by Access Manager to reflect his 
new position. 


¢ User B who currently has an active session on Identity Server and access to many protected 
resources, has been asked to leave an organization and all access to protected resources must 
be removed. By terminating user B’s session on Identity Server, any subsequent requests to 
Identity Server will require the user to login again. 
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30.3.29 


30.3.30 


The User Sessions page in Administration Console helps you to find users logged into your system 
and also helps to terminate their sessions if required. It displays the active user details for each 
Identity Server. You can search for a user with the user ID and terminate the sessions. 


1 In Administration Console Dashboard, click Troubleshooting > User Sessions. 


2 Specify the user ID and click Search. If a match is found, it lists the IP address of Identity Server 
and its sessions. 


3 Click Terminate Sessions to terminate the sessions of the specific user. 


After you have performed the above procedure, the user sessions are terminated from Identity 
Server, and any other trusted service providers it has provided an identity to during this session, 
for example, an Access Gateway or SAML 2.0 service provider. 


NOTE: User details are fetched once per administration session. The last updated date is 
displayed. To refresh the data, click on Refresh. 


Clustered Nodes Looping Due to JGroup Issues 


In a cluster when multiple nodes are down, failover does not occur and user experiences looping due 
to jgroups issues. 


Workaround:Modify the /opt/novell/nids/1ib/webapp/WEB-INF/web.xm1 file on Identity Server 
as follows to increase the jgroup timeouts. 


<context-param> <param-name>JGroupsConfiguration</param-name> <param 
value>TCP(start_port=[nidp:ClusterPort];end_port=[nidp:ClusterPort][nidp:If—xterna 
lAddress];external_addr=[nidp:ExternalAddress][nidp:EndIf]):TCPPING(initial_hosts= 
[nidp:ClusterMembers];port_range=1; timeout=3500; num_initial_members=2;up_thread=tr 
ue; down_thread=true) :MERGE2(min_interval=10000; max_interval=30000) :FD_SOCK( [nidp:I 
fExternalAddress ]bind_addr=[nidp:ExternalAddress ] [nidp: EndIf] ) :FD(shun=true; timeou 
t=5000;max_tries=5;up_thread=true; down_thread=true ) : VERIFY_SUSPECT (timeout=2000; do 
wn_thread=false;up_thread=false) :pbcast .NAKACK(down_thread=true;up_thread=true; gc_ 
lag=100; retransmit_timeout=3000) :pbcast .STABLE(desired_avg_gossip=20000; down_threa 
d=false;up_thread=false) :pbcast .STATE_TRANSFER():pbcast.GMS(merge_timeout=10000; jo 
in_timeout=5000; join_retry_timeout=2000; shun=true; print_local_addr=[nidp:DebugOn]; 
down_thread=true;up_thread=true)</param-value> </context-param> 


For more information about the timeout options, see the following links: 


¢ TCPPING 

+ MERGE2 

+ FD_SOCK 

¢ FD 

¢ VERIFY_SUSPECT 

+ NAKACK 

¢ pbcast.STATE_TRANSFER 
+ pbcast.GMS 


Authentication With Aliases Fails 


If your userstore contains alias users and if you have configured alias class for authentication, the 
authentication fails. For the workaround, see TID 7015163. 
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30.3.31 


30.3.32 


30.3.33 


nidp/app Does Not Redirect to nidp/portal after 
Authentication 


After restarting Identity Server, accessing https://idp:port/nidp/app first time does not redirect 
to https://<idp-url>: port/nidp/portal. 


Workaround: After restarting Identity Server, access User Portal first time by using https: // 
idp:port/nidp/. Afterwards, the redirection works fine. 


Login to Office 365 Fails when WS-Trust MEX Metadata Is 
Larger than 65 KB 


To workaround this issue, perform the following steps: 


1 Modify /opt/novell/nam/idp/webapps/nidp/WEB- INF/web. xml and map mex.jsp to the 
serviet mapping URL /ndip/wstrust/sts/mex as follows: 


<servlet> <servlet-name>NetIQSTS12MEX</servlet-name> <jsp-file>/jsp/mex.jsp</ 
jsp-file> <load-on-startup>1</load-on-startup> </servlet><servlet-mapping> 
<servlet -name>NetIQSTS12MEX</servlet-name> <url-pattern>/wstrust/sts/mex</url- 
pattern> </servlet-mapping> 


2 Restart Identity Server. 


Unsafe Server Certificate Change in SSL/TLS 
Renegotiations Is Not Allowed 


After upgrading Access Manager from a version earlier than 4.0 Service Pack 1, if you have 
configured Identity Server to point to the Load Balancer virtual IP address than the real IP addresses 
of the LDAP replica servers, Identity Server’s request to different LDAP server replicas fails. 


Identity Server health becomes yellow from green and displays the following warning: 
Ensure that the following replicas are operating correctly XXXX 

After validating the LDAP server replica, the following message is displayed: 

Server certificate change is restricted during renegotiation 


This happens because Access Manager uses JDK version 7u71 or later from the version 4.0 Service 
Pack 1 onwards. In JDK 7u71, unsafe server certificate change in SSL/TLS renegotiations is not 
allowed by default. 


To workaround this issue, perform any one of the following actions: 
+ Add the following line in the /opt/novell/nam/idp/conf/tomcat7.conf file: 


JAVA_OPTS="${JAVA_OPTS} -Djdk.tls.allowUnsafeServerCertChange=true" 
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30.3.34 


¢ Instead of specifying the load balancer virtual IP address as the LDAP replica server, ensure that 
Identity Server refers to each LDAP server directly and not through the load balancer. In this 
way, Identity Server maintains all communications with the LDAP servers directly, maintains 
states and connection information. 


¢ Create a wildcard certificate and assign this server certificate to all the LDAP servers in the 
replica ring. 


Viewing Request and Response Headers of All Protocols in 
a Log File 


You can use one of the following options: 


Option 1: 
Perform the following steps: 
1 Add the following filter to /opt/novell/nam/idp/conf/web. xm1: 


<filter> 

<filter -name>requestdumper</filter -name> 

<filter-class> 
org.apache.catalina.filters.RequestDumperFilter 

</filter-class> 

</filter> 

<filter -mapping> 

<filter -name>requestdumper</filter -name> 

<url-pattern>*</url-pattern> 

</filter-mapping> 


2 Add the following to the /opt/novell/nam/idp/conf/logging. properties file: 


# Dumper 

1request-dumper.org.apache.juli.FileHandler.level = INFO 
1request-dumper.org.apache.juli.FileHandler.directory = ${catalina.base}/logs 
1request-dumper.org.apache.juli.FileHandler.prefix = request-dumper. 
1request-dumper.org.apache.juli.FileHandler.formatter = 

org.apache. juli.VerbatimFormatter 
org.apache.catalina.filters.RequestDumperFilter.level = INFO 
org.apache.catalina.filters.RequestDumperFilter.handlers = 1request- 

dumper .org.apache. juli.FileHandler 


3 Update the following handler in the /opt/novell/nam/idp/conf/logging. properties file: 


handlers = icatalina.org.apache.juli.FileHandler, 
2localhost.org.apache.juli.FileHandler, 3manager.org.apache.juli.FileHandler, 
Ahost-manager.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler, 
1request-dumper.org.apache. juli.FileHandler 


A log file is created at /var/opt/novell/nam/logs/idp/tomcat/ that contains a log of all the 
headers. A sample log file format: request -dumper .2016-05-09.1og. 


Option 2: 


Add the following in /opt/novell/nam/idp/conf/tomcat .conf: 
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30.4 


30.4.1 


30.4.2 


JAVA_OPTS="${JAVA_OPTS} - 
Dcom.sun.xml.wss.provider.wsit.SecurityTubeFactory.dump=false" 
JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.xml.ws.transport.http.HttpAdapter .dump=true" 
JAVA_OPTS="${JAVA_OPTS} - 
Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true" 


Troubleshooting Analytics Server 


¢ Section 30.4.1, “When You Launch Analytics Dashboard It Displays a Blank Page,” on 
page 1218 


¢ Section 30.4.2, “The Graphs Do Not Display Any Data When You Launch Analytics Dashboard,” 
on page 1218 


¢ Section 30.4.3, “Clearing the Existing Graphs to View the Imminent Data on the Graphs,” on 
page 1219 


¢ Section 30.4.4, “Cannot Launch Analytics Dashboard after reimporting Analytics server,” on 
page 1219 


¢ Section 30.4.5, “The Analytics Server Health is Not Reported to Administration Console,” on 
page 1220 


¢ Section 30.4.6, “Analytics Dashboard Does Not Display the Graphs but Displays the Health 
Status of the Devices,” on page 1220 


¢ Section 30.4.7, “When Deploying Analytics Server in High Availability Mode, crm status Displays 
Failed Actions,” on page 1221 


When You Launch Analytics Dashboard It Displays a Blank 
Page 


If Analytics dashboard url launches a blank page initially after installing Analytics Server, you must 
perform the following on Administration Console Dashboard: 


1 Click Troubleshooting > Certificates. 
2 Click the certificate for Analytics Server. 
3 Click Re-push certificates. 


If Analytics dashboard displays blank page abruptly, then check the health of Analytics Server 
services and shared storage (for cluster setup). 


The Graphs Do Not Display Any Data When You Launch 
Analytics Dashboard 


When you launch the dashboard, it does not display data on the graphs. Also, the health of devices 
that are displayed on the graphs for Identity Server, Access Gateway, Access Gateway Clusters, and 
Identity Server Clusters is unavailable. This happens because the realtime index, where the events 
are received and stored, does not exist on the Analytics Server. 


To resolve this issue and view the realtime data graphs, perform the following steps: 


1 Connect to Analytics Server by using SSH. 


2 Run the following command to verify if the realtime events are getting stored in the realtime 
index: 
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30.4.3 


30.4.4 


Access Manager 4.3: curl -XGET 'http://localhost:9200/realtimegraphs/_search' 


Access Manager 4.3 Service Pack 1: curl -XGET 'http://localhost :9200/ 
realtimegraphsv4.3.1/_search' 


3 (Conditional) If you get the error "IndexMissingException[ [realtimegraphs ] 
missing]", "status": 404, run the following command to list all indexes that are present within 
Analytics Server: 


curl 'localhost:9200/_cat/indices?v' 


NOTE: If you have enabled the debug log for Analytics Server, you can check the realtime 
aggregator logs from /opt/novell/nam/aggregators/logs/aggregator . log. For information 
about changing the log level for any specific Analytics Server, refer Section 4.5.5, “Configuring 
Analytics Server,” on page 353. 


4 Run the following command to restart the realtime aggregator: 


/etc/init.d/novell-realtime start 


Clearing the Existing Graphs to View the Imminent Data on 
the Graphs 


If you want to clear the existing realtime data to view only the latest data on the dashboard, you must 
perform the following steps: 


NOTE: The following steps clear the data but the data is not deleted from the server. You can retrieve 
the older data by using the offline data mode. For more information about viewing the dashboard in 
offline data mode, refer 


1 Use the SSH client to connect to Analytics Server. 

2 Stop the real-time aggregator service by using the following command: 
/etc/init.d/novell-realtime stop 

3 Delete the index file by using the following command: 
Access Manager 4.3: curl -XDELETE 'http://localhost:9200/realtimegraphs ' 


Access Manager 4.3 Service Pack 1: curl -XDELETE 'http://localhost :9200/ 
realtimegraphsv4.3.1' 


4 Start the real-time aggregator service by using the following command: 
/etc/init.d/novell-realtime start 


It takes few minutes for the data to be reflected on the graphs. 


Cannot Launch Analytics Dashboard after reimporting 
Analytics server 


After importing/ re-importing an Analytics Server, you cannot access Analytics Dashboard. This 
happens when there is an issue with certificates. To resolve this issue, re-push the certificates. For 


information about re-pushing the certificates, refer the steps mentioned in Section 30.4.1, “When You 
Launch Analytics Dashboard It Displays a Blank Page,” on page 1218. 


Troubleshooting 1219 


30.4.5 The Analytics Server Health is Not Reported to 
Administration Console 


When you check the health of Analytics Server from Administration Console (Devices > Analytics 
Servers), the health for a specific Analytics Server displays the not responding icon. When you click 
on the icon, the Server is not reporting status message is displayed. To resolve this issue, you 
must restart the dashboard service by running the following command on the specific Analytics 
Server: 


/etc/init.d/novell-dashboard restart 


30.4.6 Analytics Dashboard Does Not Display the Graphs but 
Displays the Health Status of the Devices 


When you launch Analytics Dashboard, the graphs are unavailable but the Identity Server, Access 
Gateway, Access Gateway Clusters, and Identity Server Clusters graphs display the health status of 
all devices. 


All the services run properly, but the graphs are not generated. This issue occurs when Analytics 
Server does not receive the required events. 


To resolve this issue, perform the following on Administration Console: 


1 Enable required events 


For more information about enabling events for a specific graph, refer Section 18.5, “Enabling 
Events for Each Graph,” on page 999. 


Click Devices > Analytics Servers > Reports 
Log in to Reports console 

Click admin > Applications 

Click Launch Control Center 

Download and open control_center. jnlp 
In the security warning screen, click Continue 


Click Run to open the control center application 


Oo ON Oo FB WwW DN 


Click the Configuration tab 
10 On the menu bar, click Configuration > Integrator Manager 
11 Click Test 


12 (Conditional) If the test fails, restart the realtime aggregator by running the following command 
on the required Analytics Server: 


/etc/init.d/novell-realtime restart 


13 (Conditional) If the test is successful and still no graphs are displayed, then you must check the 
routing configuration. 


13a In Administration Console, click Devices > Analytics Servers > Reports. 
13b In the Reports console click Routing. 


13c Under Event Routing Rules, configure the SyslogRouting rule by clicking Edit, then 
updating the following fields if these details are not updated automatically: 
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Criteria: (((sev:[0 TO 5]) NOT st:"I" NOT st:"A" NOT st:"P") AND ("NIDS\: 

User session was authenticated" OR evt:"NIDS\: Risk based authentication 
action for user" OR rv40:"002E0606" OR rv40:"002E0525" OR rv40:"002E001F" 
OR rv40:"002E0029" OR rv40:"002E0514" OR rv40:"002E0102") ) 


Route to the following services: ALL 
Perform the following actions: Log to Syslog 


13d (Conditional) If the SyslogRouting rule is not configured, click Create to create a new event 
rule with any name and provide the same details as mentioned inStep 13c on page 1220. 


30.4.7 When Deploying Analytics Server in High Availability Mode, 
crm status Displays Failed Actions 


When you run the crm status command, if an error message is displayed with failed actions for a 
specific node, then restart cluster services by using /etc/rc.d/openais restart on that node. 


30.5 Troubleshooting Certificate Issues 


¢ Section 30.5.1, “Resolving the JCC Communication between Devices and Administration 
Console,” on page 1221 


¢ Section 30.5.2, “Resolving Certificate Import Issues,” on page 1222 

¢ Section 30.5.3, “Mutual SSL with X.509 Produces Untrusted Chain Messages,” on page 1224 
¢ Section 30.5.4, “Certificate Command Failure,” on page 1224 

¢ Section 30.5.5, “Cannot Log In with Certificate Error Messages,” on page 1225 


¢ Section 30.5.6, “When a User Accesses a Resource, the Browser Displays Certificate Errors,” 
on page 1225 


¢ Section 30.5.7, “Canceling Certificates Modification Results in Errors,” on page 1225 
¢ Section 30.5.8, “A Device Reports Certificate Errors,” on page 1225 

¢ Section 30.5.9, “Renewing the expired eDirectory certificates,” on page 1226 

¢ Section 30.5.10, “Cannot Replace Expired Certificates,” on page 1226 


30.5.1 Resolving the JCC Communication between Devices and 
Administration Console 


When the secret key in the jcc.keystore file is updated, Identity Server or Access Gateway stops 
communicating with Administration console. 


To workaround this issue, perform the following steps on the affected devices: 


1 Log in to Identity Server or Access Gateway and navigate to the JCC folder: 
Linux: /opt/novell/devman/jcc/conf 
Windows: \Program Files\Novell\devman\jcc\conf 

2 Verify if the jcc. keystore.original file exists. 

3 Ifthe jcc. keystore.original file exists, then: 
3a Replace jcc.keystore with jcc. keystore. original. 


3b Replace keystore_info.xml with keystore_info.xml.original. 
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4 Ifthe jcc. keystore.original file does not exist, then: 
4a Navigate to the JCC directory. 
Linux: /opt/novell/devman/jcc 
Windows: \Program Files\Novell\devman\jcc 
4b Run the following reimport command: 
+ On Identity Server: 
Linux: conf/reimport_nidp.sh jcc 
Windows: conf\reimport_nidp.bat jcc 
+ On Access Gateway: 
Linux: conf/reimport_ags.sh jcc 
Windows: conf\reimport_ags.bat jcc 
5 Restart JCC 
Linux: /etc/init.d/novell-jcc restart 


Windows: Navigate to Control Panel > Administrative Tools > Services, then restart the 
JcCServer service. 


6 Restart the affected devices. 


Resolving Certificate Import Issues 


Use the following sections to resolve issues created when a full certificate chain is not imported in to 
Access Manager: 

¢ Section 30.5.2.1, “Importing an External Certificate Key Pair,” on page 1222 

¢ Section 30.5.2.2, “Resolving a -1226 PKI Error,” on page 1223 


¢ Section 30.5.2.3, “When the Full Certificate Chain Is Not Returned During an Automatic Import 
of the Trusted Root,” on page 1223 


¢ Section 30.5.2.4, “Using Internet Explorer to Add a Trusted Root Chain,” on page 1224 


Importing an External Certificate Key Pair 


The Access Manager Certificate Authority requires that all certificate key pairs in . pfx format contain 
the complete certificate chain. If a key pair was created with multiple CAs and the exported certificate 
does not contain the complete certificate chain, the file cannot be imported into Access Manager. 
When you try to import such a certificate, the following error message is displayed: 


"Error importing certificate key pair: Error: Error: -1403 


When exporting the certificate key pair, ensure that you include all the certificates in the certification 
path. 


To ensure that your certificate contains all the intermediate certificates and contains them in the right 
order, import the certificate into Internet Explorer or Firefox. 


¢ For Internet Explorer, click Tools > Internet Options > Content > Certificates > Personal > 
Import. 


¢ For Firefox, click Tools > Options > Advanced > Encryption > View Certificates > Your 
Certificates > Import. 
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Make sure the browser contains the public key for all the intermediate CAs. Then select the certificate 
and export the certificate in . pfx format. In Internet Explorer, you must select to include all the 
certificates in the chain. In Firefox, all the certificates in the chain are automatically included. 


If you receive an error when importing the certificate, the error comes from either NICI or PKI. Fora 
description of these error codes, see Novell Certificate Server Error Codes and Novell International 
Cryptographic Infrastructure (http://www.novell.com/documentation/nwec/index.html). 


Resolving a -1226 PKI Error 


When you create a certificate signing request, send it to a third-party issuer to be signed, and receive 
the server certificate from the third-party issuer. You sometimes receive a -1226 error when you try to 
import the signed certificate. You receive this error when the issuer does not send the trusted roots 
required to validate the issuer of the server certificate. 


Use one of the following options to resolve this issue: 


+ If the issuer included the trusted root and any intermediate certificates in a separate file or files, 
specify these files during the import by clicking the + character that allows you to add a trusted 
root or an intermediate certificate. 


+ Ifthe issuer did not send you any additional files, you can go to the issuer’s Web site, download 
them, then specify these files during the import by clicking the + character that allows you to add 
a trusted root or an intermediate certificate. 


+ You can try importing the certificate into Internet Explorer, which has the trusted roots from all 
major CAs, then export the certificate with the required chain of trusted roots. See “Using 
Internet Explorer to Add a Trusted Root Chain” on page 1224. 


When the Full Certificate Chain Is Not Returned During an Automatic 
Import of the Trusted Root 


Access Manager allows you to automatically import the trusted root under the following conditions: 


+ When enabling SSL communication between Access Gateway and the Web server, you can 
automatically import the root CA from the Web server. 


+ When setting up the user stores for Identity Server and adding the server replicas, you can 
automatically import the root CA of the LDAP server. 


If there are multiple certificates in the chain, sometimes the server does not send all the certificates in 
the chain. When this happens, the following message is displayed: 


The root CA certificate was not returned by the server. It might be necessary 
to manually import the root CA certificate and possible intermediate CA 
certificates in order to complete the chain. 


To correct this problem, you need to manually import the missing entries. The easiest method to 
obtain all the certificates in the chain, including the root CA, is to import the server certificate into 
Internet Explorer, then export the chain and import it into Access Manager. If Access Manager 
already has some of the certificates, it skips their import and imports only the missing certificates. 


For instructions on this process, see “Using Internet Explorer to Add a Trusted Root Chain” on 
page 1224. 
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Using Internet Explorer to Add a Trusted Root Chain 


The following procedure works only when Internet Explorer contains the trusted root certificate of the 
issuer of your certificate. 

In Internet Explorer, click Tools > Internet Options > Content > Certificates. 

Click Import and import your server certificate into the Other People tab. 

Click Other People, then double-click your certificate. 

Click Certification Path. 


+ If the Certification Path shows that the certificate is OK, you now have the full certificate 
chain available for export. Click OK, then continue with Step 5. 


A WN PF 


+ If the Certification Path is not OK, you cannot use this method. Click OK, then contact your 
issuer for the certificate chain. 


5 Select the certificate, then click Export > Next. 


6 Select Cryptographic Message Syntax Standard - PKCS #7 Certificates (.P7B) as the format 
and select Include all certificates in the certification path if possible to include the certificate 
chain. 


7 Click Next, then specify a filename and path for the file. 
8 Click Next > Finish. 
9 Use this P7B file to import your server certificate into Access Manager. 


Mutual SSL with X.509 Produces Untrusted Chain Messages 


When you set up an X.509 contract for mutual SSL authentication, you must ensure that Identity 
Server trust store (NIDP-truststore) contains the trusted root from each CA that has signed the client 
certificates. If a client has a certificate signed by a CA that is not in Identity Server Trust Store, 
authentication fails. 


To add a certificate to Identity Server Trust Store: 
1 In Administration Console Dashboard, click Devices > Identity Servers > Edit > Security > NIDP 
Trust Store. 


2 Click either Add or Auto-lmport From Server and follow the prompts. 


Certificate Command Failure 


Certificate commands are generated when you upgrade Administration Console. Ensure that they 
have completed successfully. 
1 To determine whether a certificate command has failed, click Security > Command Status. 
2 Note the destination trust store or keystore of the failed command. 
3 Click Troubleshooting > Certificates. 
The Certificates page displays all the keystores and trust stores configured for Access Manager. 
4 Select the store, then click Re-push certificates. 


This sends all assigned certificates to the store. You can re-push certificates multiple times 
without causing any problems. 
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Cannot Log In with Certificate Error Messages 


After an upgrade, if users cannot log in to the access protected resources, and the failure messages 
contain certificate error messages, manually push the certificates from Administration Console to 
Access Gateway. 


To re-push a certificate: 
+ Fora reverse proxy certificate, go to the Reverse Proxy page, select a different certificate, click 
OK, return to the Reverse Proxy page, select the correct certificate, then click OK. 


+ Fora Web server certificate, go to the Web Server page, select a different SSL mutual 
certificate, click OK, return to the Web Server page, select the correct certificate, click OK, then 
apply the changes. 


When a User Accesses a Resource, the Browser Displays 
Certificate Errors 


When you configure Identity Server to use SSL (the HTTPS protocol), the browser must be 
configured to trust the CA that created the certificate for Identity Server. If you use a well-known CA, 
the browser is usually already configured to trust certificates from the CA. If you use a less-known CA 
or the Access Manager CA to create the certificate, you need to import the public key of the trusted 
root certificate into the browsers to establish the trust. For the Access Manager CA, this certificate is 
called configCA. 


For instructions on how to export the public key of a trusted root certificate, see “Viewing Trusted 
Root Details” on page 973. 


To import a public key into the browser, access the certificate options, then follow the prompts: 


+ For Internet Explorer, click Tools > Internet Options > Content > Certificates > Trusted Root 
Certification Authorities > Import. 


¢ For Firefox, click Tools > Options > Advanced > Encryption > View Certificates > Authorities > 
Import. 


Canceling Certificates Modification Results in Errors 


An Access Gateway has the following issue when the certificate modifications are canceled: 


If you make certificate changes on the Reverse Proxy or the Web Servers page, click the 
Configuration Panel link, and then cancel the changes on the Configuration page, the Reverse Proxy 
is configured with an invalid certificate. 


To correct the problem, return to the page and select the old certificate. As soon as you exit the page, 
the certificate is pushed to the device. Because you did not change the certificate, you do not need to 
restart the Embedded Service Provider. 


A Device Reports Certificate Errors 


After you restore a device, especially Administration Console, the device might report certificate 
errors. To fix these errors, you need to re-push the certificates from Administration Console to the 
device: 


1 Click Troubleshooting > Certificates. 
2 Select the store that is reporting errors, then click Re-push certificates. 
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You can select multiple stores at the same time. 


3 (Optional) To verify that the re-push of the certificates was successful, click Security > 
Command Status. 


Renewing the expired eDirectory certificates 


The Secondary Administration Console stops working when the eDirectory certificates expire. When 
a certificate is about to expire, Access Manager shows a warning message when you log in to 
Administration Console. You can check whether a certificate is expired on the Certificate Details 
page. See Section 14.1, “Viewing Certificate Details,” on page 955. 


To workaround this issue manually renew the eDirectory certificates. For more information, see 
renewing the certificates. 


Cannot Replace Expired Certificates 


When you enable signing certificate per SAML service provider, expired certificate cannot be 
replaced with an existing certificate in the signing key store. 


For example: 


Certificate 1 with alias name Cert1 is assigned to Service Provider 1 and Certificate 2 with alias name 
Cert2 is assigned to Service Provider 2. If Cert1 has expired and the user wants to use Cert2 instead 
of Cert1, the user cannot replace Cert1 with Cert2 because Cert2 is already existing in the signing 
key store. 


To workaround this issue, perform the following steps: 


1 Add Cert2 with a different name (Cert4) and alias name Cert1. 
2 Select Cert1, click Replace and select Cert4 (certificate created in the previous step). 


Troubleshooting Access Manager Policies 


This section discusses the following topics: 


¢ Section 30.6.1, “Turning on Logging for Policy Evaluation,” on page 1227 


¢ Section 30.6.2, “Common Configuration Problems That Prevent a Policy from Being Applied as 
Expected,” on page 1228 


¢ Section 30.6.3, “The Policy Is Using Old User Data,” on page 1230 

¢ Section 30.6.4, “Form Fill and Identity Injection Silently Fail,” on page 1232 
¢ Section 30.6.5, “Checking for Corrupted Policies,” on page 1232 

¢ Section 30.6.6, “Policy Page Timeout,” on page 1232 

¢ Section 30.6.7, “Policy Creation and Storage,” on page 1232 

¢ Section 30.6.8, “Policy Distribution,” on page 1233 

¢ Section 30.6.9, “Policy Evaluation: Access Gateway Devices,” on page 1234 
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Turning on Logging for Policy Evaluation 


Policy evaluation for roles occurs at Identity Server. For Authorization and Identity Injection policies, 
policy evaluation occurs on the Embedded Service Provider (ESP) where the policy is enabled. 


For the Form Fill policies, the evaluation and logging is done by ESP and the proxy service. To set the 
logging level on Access Gateway for the proxy service, see “Enabling Form Fill Logging” on 
page 1287. 


Logging for the policy evaluation done by ESP is controlled by the log settings of Identity Server 
configuration. To enable this type of logging: 
1 Click Devices > Identity Servers > Edit > Auditing and Logging. 


If you have set up more than one Identity Server configuration, ensure that you select the 
configuration to which the other Access Manager components have been assigned. 


2 Select Enabled for File Logging. 
3 Select to echo the trace messages to the console: 


+ For the Linux Access Gateway Appliance, Linux Access Gateway Service, or Linux Identity 
Server, this sends the messages to the catalina. out file. 


+ For the Linux Access Gateway Service or Windows Identity Server, this sends the 
messages to the stdout. log file. 


4 (Optional) Specify a path for Identity Server log files. 


If you have a mixed platform environment (for example, Identity Server is installed on Windows 
and Access Gateway is on Linux), do not specify a path. 


5 For policy evaluation tracing, set the Application level to info in the Component File Logger 
Levels section. 


If you are only troubleshooting policies at this time, do not select any other options. This reduces 
the amount of information recorded in the log files. 


To see the policy SOAP messages, you need to set the Application level to verbose. 
6 Update Identity Server. 
7 Click Auditing > General Logging and download Identity Server and ESP catalina.out logs. 


¢ For role evaluation traces, view Identity Server catalina. out file (Linux) or the 
stdout . log file (Windows). 


If your Identity Servers are clustered, you need to look at the file from each Identity Server. 


+ For Authorization, Form Fill, and Identity Injection evaluation traces, view the log file of ESP 
of the device that is protecting the resource. 


è Linux Access Gateway Appliance or Service: This is the catalina. out file of 
Access Gateway where the protected resource is defined. If Access Gateway is part of 
a cluster, you need to look at this file from each Access Gateway in the group. 


To view the actual ESP log file that contains only ESP log messages, see the 
nidp.*.xm1 files in the /var/opt/novell/tomcat7/webapps/nesp/WEB- INF/logs 
directory (or the directory you specified in Step 4). Depending upon how you have 
configured File Wrap, the * portion of the filename contains the month, the week, the 
day, and the hour. 
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+ Windows Access Gateway Service: This is the stdout . log file of Access Gateway 
where the protected resource is defined. If Access Gateway is part of a cluster, you 
need to look at this file from each Access Gateway in the group. 


To view the actual ESP log file that contains only ESP log messages, see the 
nidp.*.xml1 files in the \Program Files\Novell\tomcat \webapps\nesp\WEB- 

INF\ logs directory (or the directory you specified in Step 4). Depending upon how you 
have configured File Wrap, the * portion of the filename contains the month, the week, 
the day, and the hour. 


8 To understand what you are looking for in the log file, continue with one of the following: 
+ “Understanding Policy Evaluation Traces” on page 1273 if you set Application level to info. 


¢ Section 30.6.9, “Policy Evaluation: Access Gateway Devices,” on page 1234 if you set 
Application level to verbose. 


Common Configuration Problems That Prevent a Policy 
from Being Applied as Expected 


When you try to determine what is functioning incorrectly in a policy, you need to turn on policy tracing 
and understand the evaluation traces. See the following: 

¢ Section 21.6, “Turning on Logging for Policy Evaluation,” on page 1062 

¢ “Understanding Policy Evaluation Traces” on page 1273 
The CO entry line of a policy trace identifies when a policy condition evaluates to False or True. The 
PA entry line indicates whether the Action was applied or ignored. If the results of the policy trace are 
not what you expected for the user, the next step is to determine why the policy isn’t behaving the 
way you want it to. Check for the following problems: 

¢ Section 30.6.2.1, “Enabling Roles for Authorization Policies,” on page 1228 

¢ Section 30.6.2.2, “LDAP Attribute Condition,” on page 1229 

¢ Section 30.6.2.3, “Result on Condition Error Value,” on page 1229 

¢ Section 30.6.2.4, “An External Secret Store and Form Fill,” on page 1230 


Enabling Roles for Authorization Policies 


If you are using roles in your authorization policies, you need to ensure that the role is enabled for 
Identity Server configuration. You can create roles and authorization policies independently of 
assigning them to protect a resource or to an Identity Server configuration. 


If you have not enabled the role, users are not assigned the role when they log in, even when they 
meet all the criteria for the role. 


¢ |f the Authorization Policy is an Allow policy, the users might be denied access because they 
haven’t been assigned the role. 


+ Ifthe Authorization Policy is a Deny policy, the users might be allowed access because they 
haven’t been assigned the role. 


Whenever an Authorization Policy is not producing the expected results and the policy contains a 
role, the first troubleshooting step should always be to check whether the role has been enabled for 
Identity Server configuration. Click Devices > Identity Servers > Edit > Roles. If the role is not 
enabled, Identity Server cannot assign the role to the user. 
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The second step should be to ensure that the roles are transferred from for Identity Server to the 
Embedded Service Provider. Click Devices > Identity Servers > Edit > Liberty > Web Service 
Provider. The Authentication Profile needs to be enabled in order for Embedded Service Providers 
to evaluate roles in policies. This profile is enabled by default, but it can be disabled. When it is 
disabled, all devices assigned to use this Identity Server cluster configuration cannot determine which 
roles a user has been assigned, and the devices evaluate policies as if the user has no roles. 


LDAP Attribute Condition 


If you use an LDAP attribute as the condition for a Role policy or an Authorization policy and your 
users are not being assigned the role or are denied access to a resource, the most likely cause of the 
problem is the LDAP attribute name used in the policy. Some administration tools for the LDAP user 
stores display a Ul name or an eDirectory™ name rather than the LDAP attribute name. Access 
Manager policies require the LDAP attribute name. 


Use the following steps to identity whether the Access Manager policy has been configured for the 
LDAP attribute name, a UI name, or an eDirectory name: 
1 Use an LDAP browser to view one of your users in your LDAP user store. 
You can download a Java-based tool from the Internet. 
2 Verify the LDAP name of the attribute and that the user has the expected value. 


3 In Administration Console Dashboard, click Policies > Policies > [Name of Policy] > Rule 
Number. 


4 View the attribute name and value for the LDAP Attribute condition. 
5 Verify the following: 


+ The name of the attribute should match the name as displayed in the LDAP browser. The 
attribute name is not case sensitive, but it should not contain any spaces. If you need to 
modify the attribute used by the policy, click the attribute name, then select an attribute from 
the list or select New LDAP Attribute to add one. 


+ The value can be case sensitive, depending upon how you have configured the Mode for 
the policy. If you have selected case sensitive for the Mode, ensure that the case in the 
policy matches the case in the LDAP user store. 


+ Ifthe attribute is multi-valued and your users typically have multiple values, select 
Substring as the Comparison type. 


6 If these steps have not solved the problem, see “Result on Condition Error Value” on page 1229. 


Result on Condition Error Value 


If you incorrectly set the value of the Result on Condition Error field, you create a policy that allows 
an action that you want the policy to deny or that denies an action that you want allowed. You must 
carefully evaluate whether you want the action applied or ignored when an error occurs during the 
evaluation of the condition. For positive conditions, the following rules apply: 


+ For the action to be applied, either the user must match the condition or the Result on Condition 
Error must be set to True. 

+ For the action to be ignored, either the user must not match the condition or the Result on 
Condition Error must be set to False. 


The logic is harder to follow when you start adding “if not” to the conditions. The user then matches 
the condition by not matching the condition. For this type of condition, you need to ask whether you 
want the action applied to any user when an error occurs evaluating the condition. 
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The logic is even harder to following when you start adding multiple condition groups that can also 
have “or nots” and “if nots”. 


If you have a policy that uses “if not” conditions or uses multiple condition groups and it is not 
producing the expected results, you might want to rewrite the policy so that it contains only positive 
conditions. 


You might want to modify the condition groups so that the policy uses multiple rules, with each rule 
containing one condition group with the conditions you want the user to match for the action you 
assign to the rule. 


30.6.2.4 An External Secret Store and Form Fill 


When you create a user store on Identity Server (Local > User Stores) and define it as an external 
Secret Store (Liberty > Web Service Provider > Credential Profile), some attributes are not being 
created properly on the SAML affiliate object. The workaround is to access the user store 
configuration page (Local > User Stores), then exit. This action results in a check to verify that the 
schema, objects, and attributes exist, and the affiliate object is then re-created from scratch, if 
necessary. 


The following affiliate objects must exist: 


authsamlCertContainerDN (container holding trusted certificates, 
for example: SCC Trusted Root.Security) 

authsamlProviderID 

authsamlTrustedCertDN (list of trusted certificate(s) ) 

authsamlValidAfter (180 seconds default) 

authsamlValidBefore (180 seconds default) 


If these attributes exist, the system works normally. However, if your Identity Server and Secret Store 
server are not configured to use the same NTP server, time synchronization can be a problem. If time 
synchronization is an issue, you can change the 180-second default validity times as a workaround. 


If your LDAP user store and Administration Console have a firewall separating them, TCP ports 524 
and 636 must be open to allow for the creation of the required objects. For more information about 
ports and firewalls, see Setting Up Firewalls in the NetlQ Access Manager 4.3 Installation and 
Upgrade Guide. 


30.6.3 The Policy Is Using Old User Data 


When a policy is first evaluated, it caches information about the user. 


+ Some data items are updated every minute. 
+ Some are cached for the duration of the request. 


+ Some are cached for the duration of the user’s session. When a data item is cached for the 
duration of a user session, the user must log out and log in for the policy modification to take 
effect. 


Table 30-2 lists how long the data items for a condition are cached before being refreshed. 


Table 30-2 Data Caching Limits 


Condition Data Refresh Interval 


Authenticating IDP User session 
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Condition 


Authentication Contract 
Authentication Method 
Authentication Type 
Client IP 

Credential Profile 
Current Date 

Current Day of Week 
Current Day of Month 
Current Time of Day 
HTTP Request Method 
Java Data Injection Module 


LDAP Attribute 


LDAP Group 

LDAP OU 

Liberty User Profile 

Proxy Session Cookie 
Roles for Current User 
Roles from Identity Provider 


Shared Secret 


String Constant 
URL 

URL Scheme 

URL Host 

URL Path 

URL File Name 
URL File Extension 
User Store 


X-Forwarded-For IP 


Data Refresh Interval 


User session 
User session 
User session 
Request 
User session 
One minute 
One minute 
One minute 
One minute 
Request 


User session 


User session; configurable to be cached only for the 
request with the Force Data Read option. 


User session 
User session 
User session 
User session 
User session 


User session 


User session; configurable to be cached only for the 
request with the Force Data Read option. 


User session 
Request 
Request 
Request 
Request 
Request 
Request 
User session 


Request 
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30.6.4 Form Fill and Identity Injection Silently Fail 


Login with Form Fill or Identity Injection can fail when all of the following conditions occur: 


¢ Your user store is configured to use Novell® SecretStore®. 


+ The shared secrets needed for Form Fill or Identity Injection are locked because the shared 
secrets are used by another application that is using the enhanced security feature. For 
example, if the application writes a secret called ssn, and you use that same secret in a Form Fill 
or Identity Injection policy, that secret is locked whenever the admin changes the user’s 
password. Access Manager does not use the enhanced security feature when it writes shared 
secrets. 


The new unlock feature for SecretStore can resolve this issue. See “Determining a Strategy for 
Unlocking the SecretStore” on page 368. 


30.6.5 Checking for Corrupted Policies 


For a policy to be evaluated correctly, the policy must contain a rule. To verify that your system does 
not contain any policies with configuration errors: 


1 In Administration Console Dashboard, click Troubleshooting > Policies. 
If you have any corrupted policies, they appear in the list. 
2 Identify the corrupted policy, then click Remove. 


30.6.6 Policy Page Timeout 


If your policy page hangs, and you have an LDAP group or LDAP ou being used in the policy, check 
the health of your user stores (LDAP servers) and ensure that they are communicating. 


30.6.7 Policy Creation and Storage 


For troubleshooting, you can export the policy and send it to NetIQ for debugging. If the policy uses 
roles, ensure that you also export the Role policies. 


Policies are stored as XML documents in the object directory, with one XML document to represent 
each policy container. The default policy container (Master_Container) resides at: 


\\novell\accessManagerContainer\VCDN_Root\PartitionsContainer\Partition\ContentPub 
lisherContainer\mastercdn\xpem1PEP\romaContentCollectionXMLDoc 


Other policy containers are stored following the same path, with a unique name string representing 
the policy name that replaces the ou=mastercdn portion of the above path. 


If you are unsure if the policy is being created correctly or if you need to check to see if the policy is 
enabled, you can view the policy list in the interface. If you think the GUI is not properly displaying the 
policy, you can also view the XML by navigating to the Policy Conditions on which you edit rules, right 
click and choose This Frame > View Frame Source. 
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Policy Distribution 


Policy definitions are not replicated, but are referenced by Access Gateways for which the policy is to 
be evaluated. The policy reference mechanism is a set of XML elements that refer back to the policy 
definitions stored in the various policy containers. If you have configured a policy for a protected 
resource and an Access Gateway does not seem to be executing this policy, use the following 
procedures to verify that Access Gateway has been configured to use the policy: 


1 Set the level of Application logging to verbose. See Section 21.6, “Turning on Logging for Policy 
Evaluation,” on page 1062. 


This enables the tracing of the policy enforcement lists. 


2 Search for name of your policy in a <PolicyEnforcementList> element. The 
ExternalElementRef attribute contains a reference to the policy name. 


You can find these elements in the catalina. out file (Linux) or stdout.1log file (Windows). 


3 If you cannot find the policy name, Access Gateway has not been configured to use the policy. 
The configuration either needs to be applied or the policy needs to be enabled. For information 
about how to assign a policy to a protected resource, see Section 3.8.4, “Configuring Protected 
Resources,” on page 128. 


4 If you find the policy name associated with the correct protected resource, you need to check 
why the policy is not evaluating according to your design. Set the level of Application logging to 
info and examine the policy trace from a user accessing the protected resource. See 
“Understanding Policy Evaluation Traces” on page 1273. 
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Policy Evaluation: Access Gateway Devices 


The following diagram depicts how Authorization policies fit into the protected resource processing for 
the proxy. 


Figure 30-8 Policy Evaluation 


Request Received 


NO 


2 


Policies for Access Gateway devices are evaluated by the policy engine in Java. A SOAP interface is 
used to transition from the proxy to Java and back. To see the SOAP messages, you need to set the 
logging level of the Application level to verbose. See Section 21.6, “Turning on Logging for Policy 
Evaluation,” on page 1062. 


Cee 


The SOAP messages are output to the catalina.out file (Linux) or stdout . log file (Windows). 
Sample SOAP messages are shown in the following scenarios: 

¢ Section 30.6.9.1, “Successful Policy Configuration Example,” on page 1235 

¢ Section 30.6.9.2, “No Policy Defined Configuration Example,” on page 1235 

¢ Section 30.6.9.3, “Deny Access Configuration/Evaluation Example,” on page 1236 
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30.6.9.1 Successful Policy Configuration Example 


Note the Policy Enforcement Point (PEP) identifier of AGIdentitylnjection in the request and the 
PolicyID in the response. 


Configuration Request 


toBufSeg: <?xml version="1.0" encoding="UTF-8"?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ 
envelope/"> 
<SOAP - ENV : Body> 
<NXPES ID="12"> 
<Configure-ag PEPName="AGIdentityInjection"> 
<PolicyEnforcementList 
RuleCombiningAlgorithm="DenyOverrideswithPriority" 
schemaVersion="1.32" 
LastModified="1138389868885" 
LastModifiedBy="cn=admin, o=novell"> 
<PolicyRef ElementRefType="ExternalWithIDRef" 
ExternalElementRef="PolicyID_xpemlPEP_AGIdentity 
Injection_ii_test" 
ExternalDocRef="0u=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, 
ou=PartitionsContainer, ou=VCDN_Root, ou=access 
ManagerContainer, o=novell: romaContentCollection 
XMLDoc" 
UserInterfaceID="PolicyID_xpem1lPEP_AGIdentity 
Injection_ii_test"/> 
</PolicyEnforcementList> 
</Configure-ag> 
</NXPES> 
</SOAP-ENV: Body> 
</SOAP-ENV: Envelope> 


Configuration Response 


LibertyProcessMsgCB: 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> 
<SOAP-ENV: Body> 
<NXPES Id="" Status="Success"> 
<ConfigureResponse PolicyId="7550K8P60- 7543 -518M-8L8M-NOP2LM2 
N3027"> 
<ContextDataElement Enum="2551"/> 
</ConfigureResponse> 
</NXPES> 
</SOAP-ENV: Body> 
</SOAP-ENV: Envelope> 


30.6.9.2 No Policy Defined Configuration Example 


The following is a sample of a configuration request where the policy code detects that no policies are 
in effect for the protected resource and Policy Enforcement Point (PEP). 
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Configuration Request 


toBufSeg: <?xml version="1.0" encoding="UTF-8"?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> 
<SOAP - ENV: Body> 
<NXPES ID="11"> 
<Configure-ag PEPName="AGAuthorization"> 
<PolicyEnforcementList 
RuleCombiningAlgorithm="DenyOverrideswithPriority" 
schemaVersion="1.32" 
LastModified="1138389868885" 
LastModifiedBy="cn=admin, o=novell"> 
<PolicyRef ElementRefType="ExternalWithIDRef" 
ExternalElementRef="PolicyID_xpemlPEP_AGIdentity 
Injection_ii_test" 
ExternalDocRef="0u=xpem1PEP, ou=mastercdn, ou=Content 
PublisherContainer, ou=Partition, ou=Partitions 
Container, ou=VCDN_Root, ou=accessManager 
Container, o=novell: romaContentCollectionXMLDoc" 
UserInterfaceID="PolicyID_xpem1PEP_AGIdentityInjection_ 
ii_test"/> 
</PolicyEnforcementList> 
</Configure-ag> 
</NXPES> 
</SOAP-ENV: Body> 
</SOAP-ENV: Envelope> 


Configuration Response 


LibertyProcessMsgCB: 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ 
envelope/"> 
<SOAP - ENV : Body> 
<NXPES Id="" Status="emptypolicyset"/> 
</SOAP - ENV : Body> 
</SOAP-ENV: Envelope> 


30.6.9.3 Deny Access Configuration/Evaluation Example 


The following is a sample of a configuration request for a Deny policy and an evaluation request for 
this policy 


Configuration Request 


toBufSeg: <?xml version="1.0" encoding="UTF-8"?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ 
envelope/"> 
<SOAP - ENV : Body> 
<NXPES ID="17"> 
<Configure-ag PEPName="AGAuthorization"> 
<PolicyEnforcementList 
RuleCombiningAlgorithm="DenyOverrideswithPriority" 
schemaVersion="1.32" 
LastModified="1138718667305" 
LastModifiedBy="cn=admin, o=novell"> 
<PolicyRef 
ElementRefType="ExternalwithIDRef" 
ExternalElementRef="PolicyID_xpemlPEP_AGIdentityInjection 
_custom_test" 
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ExternalDocRef="0u=xpem1PEP, ou=mastercdn, ou=Content 
PublisherContainer, ou=Partition, ou=PartitionsContainer, 
ou=VCDN_Root, ou=accessManagerContainer, o=novell: roma 
ContentCollectionXMLDoc" 

UserInterfaceID="PolicyID_xpemlPEP_AGIdentityInjection 
_custom_test"/> 

<PolicyRef 

ElementRefType="ExternalwithIDRef" 

ExternalElementRef="PolicyID_xpem1lPEP_AGAuthorization_ 
deny-all" 

ExternalDocRef="0u=xpem1PEP, ou=mastercdn, ou=Content 
PublisherContainer, ou=Partition, ou=PartitionsContainer, 
ou=VCDN_Root, ou=accessManagerContainer, o=novell: roma 
ContentCollectionXMLDoc" 

UserInterfaceID="PolicyID_xpem1lPEP_AGAuthorization 
_deny-all"/> 

</PolicyEnforcementList> 
</Configure-ag> 
</NXPES> 
</SOAP-ENV: Body> 
</SOAP-ENV: Envelope> 


Configuration Response 


LibertyProcessMsgCB: 

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ 
envelope/"> 

<SOAP - ENV : Body> 
<NXPES Id="" Status="success"> 

<ConfigureResponse 
PolicyId="55N3NL81-L29N-2619-KOM8-2L963MOMM701"/> 

</NXPES> 

</SOAP -ENV : Body> 

</SOAP-ENV: Envelope> 


Evaluation Request 


toBufSeg: <?xml version="1.0" encoding="UTF-8"?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> 
<SOAP - ENV : Body> 

<NXPES ID="18"> 

<Evaluate PolicyId="55N3NL81-L29N-2619-KOM8-2L963MOMM701" 
Verbose="on"/> 

</NXPES> 
</SOAP -ENV : Body> 
</SOAP-ENV: Envelope> 


Troubleshooting 1237 


Evaluation Response 


LibertyProcessMSsgCB: 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/ 
envelope/"> 
<SOAP - ENV : Body> 
<NXPES Id="" Status="success"> 
<EvaluateResponse> 
<DoAction ActionName="Deny" ActionTTL="-1" Enum="2620"> 
<Parameter Enum="10" Name="Message" Value=""/> 
</DoAction> 
</EvaluateResponse> 
</NXPES> 
</SOAP - ENV : Body> 
</SOAP -ENV : Envelope> 


30.7 Troubleshooting MobileAccess 


This section discusses how to troubleshoot issues that occur when using MobileAccess. 
¢ Section 30.7.1, “Using the Same Mobile Device for Different Users Causes the Expired Session 
Error,” on page 1238 


¢ Section 30.7.2, “Simple Authentication with a Pop-up Browser Window Does Not Work for 
MobileAccess,” on page 1238 


¢ Section 30.7.3, “Users Fail to Authenticate to MobileAccess when Appmarks Are Launched in 
the Chrome Browser,” on page 1239 


¢ Section 30.7.4, “Changes to MobileAccess do not Appear in Administration Console,” on 
page 1239 


30.7.1 Using the Same Mobile Device for Different Users Causes 
the Expired Session Error 


Issue: You have a company iPad or Android tablet. User1 has registered and used the tablet with the 
company and then left the company. You deregister User1 and then reassign the tablet to User2. After 
User 2 registers the tablet and tries to access an appmark, they get an error of expired session. 


Solution: The user must try the appmark a second time and then they can access the resource. The 
reason for this is a cookie still exists for User1, who no longer is valid. The second attempt replaces 
the cookie with a valid cookie for User2. 


30.7.2 Simple Authentication with a Pop-up Browser Window Does 
Not Work for MobileAccess 


Issue: You have a web server configured to use simple authentication. Simple authentication 
requires a pop-up browser window for authentication. The users receives a 401 error. 


Solution: Mobile platforms do not support pop-up browser windows. Any web server that requires a 
simple authentication, using a pop-up browser window, fails in the mobile environment with the 
internal browser. DO not use pop-up browsers windows for authentication in a MobileAccess 
environment.(948904) 
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30.7.3 


30.7.4 


Users Fail to Authenticate to MobileAccess when Appmarks 
Are Launched in the Chrome Browser 


Issue: If a user sets up a Chrome profile and then tries to use a Google Apps resource configured to 
use Chrome on MobileAccess, the login fails because Chrome passes the saved profile user name 
and password to the resource instead of passing the user name and password from MobileAccess. 
This issue occurs for any Google Apps resource (for example, Gmail or Google Drive) on iOS and 
Android mobile devices. (Bug 948622) 


Solution: Users can remove their Chrome profile to avoid this issue, or you can configure the 
appropriate Google Apps appmarks in Access Manager so the resources open with Firefox, an 
internal viewer, or a user-selectable option, instead of Chrome. 


Changes to MobileAccess do not Appear in Administration 
Console 


Issue: If you have more than one Administration Console, after you make changes to MobileAccess 
and save the changes, the changes do not appear in Administration Console. 


Solution: Access Manager synchronizes the changes between Administration Consoles and this can 
take some time. There is a built-in delay so that the changes have time to synchronize between 
Administration Consoles. If you need a further delay than the built-in delay, you can increase the 
delay with a Java parameter. The Java parameter is defined in a configuration file on Linux and as a 
registry key on Windows servers. 


This problem occurs when you change the Branding of the User Portal page as well. If you make the 
change for MobileAccess, you do not need to make additional changes to fix Branding. The solution 
is the same for both features. 


To add the Java parameter: 
1 (Conditional) If you have a Linux server, you must edit the tomcat7.conf file located here /opt/ 
novell/nam/adminconsole/conf/tomcat7.conf. 
1a Open the tomcat7.conf file in a text editor. 
1b Add the following parameter with a delay value that is appropriate for your environment: 


JAVA_OPTS="${JAVA_OPTS} -DAMSrvDoorBellDelay=10000" 


The value is in milliseconds. This example increases the delay to 10 seconds. 
1c Save and close the tomcat7.conf file. 
1d Restart Tomcat to have the parameter take effect. 


/etc/init.d/novell-ac restart 


2 (Conditional) If you have a Windows server, you must add a registry key. 
2a Launch the Registry Editor as an administrator, by clicking Start > Run, then enter regedit. 


2b Inthe left pane of the Registry Editor, navigate to My Computer > HKEY_ LOCAL MACHINE 
>SOFTWARE > Wow6432Node > Apache Software Foundation > Procurn2.0 > Tomcat7 > 
Parameters > Java. 


2c Double-click Options in the right pane of the Registry Editor. 
2d Add the following key with the delay value that is appropriate for your environment: 


-DAMSrvDoorBellDelay=10000" 


Troubleshooting 1239 


30.8 


30.8.1 


30.8.1.1 


30.8.2 


The value is in milliseconds. This example increases the delay to 10 seconds. 
2e Close the Registry Editor. 
2f Restart Tomcat by using the following commands: 


net stop Tomcat7 
net start Tomcat7 


Troubleshooting Code Promotion 


e Section 30.8.1, “Troubleshooting Identity Server Code Promotion,” on page 1240 
è Section 30.8.2, “Troubleshooting Access Gateway Code Promotion,” on page 1240 


¢ Section 30.8.3, “Troubleshooting Device Customization Code Promotion,” on page 1244 


Troubleshooting Identity Server Code Promotion 


This section discusses how to troubleshoot any issue occurred during Identity Server Code 
Promotion. 


Importing Identity Server Configuration Data Fails 

Error message: Configuration Import Failed 

While importing the configuration data, the Import Configuration wizard displays this message. 
See the details of the failure Administration Console tomcat logs at the following location: 
Linux: /opt/novell/nam/adminconsole/logs/catalina.out 

Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.1log 

Windows: \Program Files (x86)\Novell\Tomcat\logs\stderr.1log 

Collect the error details and contact the Technical Support team. 


To restore your system, go to the Dashboard and click the drop-down menu in the upper right corner 
> Code Promotion. You will find the backup file that was created as part of import. Download the file 
and then click Import Configuration on the same page. Re-import this backup configuration to restore 
to the previous configuration. 


Troubleshooting Access Gateway Code Promotion 


This section discusses how to troubleshoot any issue occurred during Access Gateway Code 
Promotion. 

¢ Section 30.8.2.1, “Importing Access Gateway Configuration Data Fails,” on page 1241 

¢ Section 30.8.2.2, “Policy Configuration Is Locked,” on page 1241 

¢ Section 30.8.2.3, “Access Gateway Configuration Is Locked,” on page 1241 


¢ Section 30.8.2.4, “Access Gateway Cluster Is Not Associated with any Identity Server,” on 
page 1242 


¢ Section 30.8.2.5, “Proxy Service Type Does Not Match,” on page 1242 
¢ Section 30.8.2.6, “Policy Type Does Not Match,” on page 1242 
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30.8.2.1 


30.8.2.2 


30.8.2.3 


¢ Section 30.8.2.7, “Cannot Import a Virtual Proxy Service to SSL enabled Master Proxy,” on 
page 1242 


¢ Section 30.8.2.8, “Cookie Domain and Published DNS Name Do Not Match,” on page 1242 


¢ Section 30.8.2.9, “SSL Enabled Web Server Configuration Is Imported to a Non-SSL Proxy 
Service,” on page 1243 


¢ Section 30.8.2.10, “Names of Master Proxy Service Are Different,” on page 1243 

¢ Section 30.8.2.11, “Reverse Proxy and Master Proxy Service Do Not Exist,” on page 1243 
¢ Section 30.8.2.12, “Proxy Service Does Not Exist in the Target Setup,” on page 1243 

¢ Section 30.8.2.13, “DNS Name Is Not Unique,” on page 1243 

¢ Section 30.8.2.14, “Revert Process Fails for Access Gateway,” on page 1243 


Importing Access Gateway Configuration Data Fails 


Error message: Configuration Import Failed 

While importing the configuration data, the Import Configuration wizard displays this message. 
See the details of the failure Administration Console tomcat logs at the following location: 
Linux: /opt/novell/nam/adminconsole/logs/catalina.out 

Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.1log 

Windows: \Program Files (x86)\Novell\Tomcat\logs\stderr.1log 

Collect the error details and contact the Technical Support team. 


You can restore Access Gateway configuration by using the backup file if you have backed up the 
configuration by using the ambackup file. 


Policy Configuration Is Locked 


Error message: Policy configuration locked by another user 


If an administrator is making changes to policies and you try to import the configuration by using 
Code Promotion simultaneously, then import fails. 


Ensure that while importing, no other administrator is making changes to configuration. If it is already 
locked, click Please unlock to override. 


You also need to check which policy containers are locked and then unlock them from the Policy user 
interface. 


Access Gateway Configuration Is Locked 


Error message: Access Gateway configuration locked by another user 


If an administrator is making changes to Access Gateway configuration and you try to import the 
configuration by using Code Promotion simultaneously, then import fails. 


Ensure that while importing, no other administrator is making changes to configuration. If it is already 
locked, click Please unlock to override. Unlock Access Gateway cluster in Access Gateway user 
interface for which you are importing the configuration data. 
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Access Gateway Cluster Is Not Associated with any Identity Server 


Error message: Could not generate Access Gateway import overview 


Ensure that you associate Access Gateway cluster with an Identity Server cluster before importing 
protected resources that have Identity Server dependencies such as contracts and custom attributes. 


Proxy Service Type Does Not Match 


Error message: Proxy service name not unique 


If the name of a proxy service is same on the source and target systems, but their type does not 
match, then the import does not happen. For example, a proxy service is Path Based Multi-Homing 
on the source setup and a proxy service with the same name is Domain Based Multi-Homing on the 
target system. 


Update the type of the proxy service on the source setup or target setup and then import. 


Policy Type Does Not Match 


Error message: Invalid input 


Type Mismatch Error: Cannot import policy <name of the policy> of container <name 
of the container>. The type of this policy is <type of policy> in the source setup 
and <type of policy> in the target setup. 


If the name of a policy is same on the source and target systems, but their type does not match, then 
the import does not happen. For example, a policy is defined as authorization policy in the source 
setup and a policy with the same name is defined as identity injection in the target setup. 


Update the type of the policy on the source setup or target setup and then import. 


Cannot Import a Virtual Proxy Service to SSL enabled Master Proxy 


Error message: Invalid input 


Cannot import the new virtual proxy service in (name of reverse proxy) > (name of 
proxy service) from source Access Gateway cluster <name of the cluster> because SSL 
is enabled in the reverse proxy <name of the reverse proxy on the target system> in 
the target Access Gateway cluster. 


Import of virtual proxy services to a SSL enabled proxy service in the target system is not allowed.In 
such cases, ensure that you exclude virtual proxy services during import. 


Cookie Domain and Published DNS Name Do Not Match 


Error message: Domain-Based Multi-Homing requires the Published Domain Name of proxy 
service <name of the proxy service being imported> to be in the Cookie Domain of 
the first Proxy Service under Reverse Proxy 


Master proxy service's cookie domain does not match with the imported Domain Based Proxy 
Service's DNS name. 


Update the published DNS name for the specified proxy service while importing it. 
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SSL Enabled Web Server Configuration Is Imported to a Non-SSL 
Proxy Service 
Error message: Invalid input 


Cannot import the SSL enable proxy service in (name of reverse proxy) > (name of 
proxy service) from the source Access Gateway cluster because SSL is not enabled in 
the reverse proxy in the target Access Gateway cluster 


You cannot import SSL enabled proxy service to non SSL enabled reverse proxy. Before importing, 
enable SSL for the target reverse proxy or disable SSL for source proxy service. 


Names of Master Proxy Service Are Different 


Error message: Invalid input 


Cannot import master proxy service from the source Access Gateway cluster as 
another master proxy service with a different name already exists in the target 
Access Gateway cluster. 


Name of the master proxy service must be same on the source and target systems. Update the name 
on the source or target setup before importing it. 


Reverse Proxy and Master Proxy Service Do Not Exist 


Error message: Invalid input 
Reverse Proxy does not exist in the target Access Gateway cluster 


For importing a proxy service or protected resource, if the corresponding reverse proxy or master 
proxy service does not exist, then you must create reverse proxy and master proxy service on the 
target system before starting the Code Promotion import. 


Proxy Service Does Not Exist in the Target Setup 

Error message: Invalid input 

Proxy Service does not exist in the target Access Gateway cluster 

Importing only selected protected resources for a domain-based proxy service that does not exist in 


the target setup fails. You must also import the related domain-based proxy service in such cases. 


DNS Name Is Not Unique 


Error message: Published DNS Name is not unique under Reverse Proxy in the target 
setup. 


DNS name must be unique under a reverse proxy. Specify a unique name in the Published DNS 
Name field for the proxy service during import. 


Revert Process Fails for Access Gateway 


In case of any error during the import process, system tries to revert to the previous configuration. If 
any error occurs during this revert process, then Code Promotion displays a message specifying the 
component for which the revert process failed. Components include Access Gateway configuration 
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and dependent policies and policy extensions. In this case, you need to restore the pre-import 
configuration manually by using ambackup. You should take a backup by using the ambackup file 
before importing the configuration data. 


Troubleshooting Device Customization Code Promotion 


This section discusses how to troubleshoot any issue occurred during device customization Code 
Promotion. 


Custom Files Are Not Imported 


Ensure that the custom files are available in the source setup and paths are correct. 


Verify the following Administration Console log file of the source setup after export. This log file 
contains information about files that are not exported. 


¢ Linux: /opt/novell/nam/adminconsole/logs/catalina. out 
+ Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout. log 


Troubleshooting the Device Fingerprint Rule 


¢ Section 30.9.1, “Enabling the Debug Option for the Device Fingerprint Rule,” on page 1244 


¢ Section 30.9.2, “Using Logs to Understand How the Device Fingerprint Rule Is Evaluated,” on 
page 1244 


Enabling the Debug Option for the Device Fingerprint Rule 


When enabled, the debug option shows all parameters fetched from the browser before submitting 
the fingerprint. 


Perform the following steps to enable the debug option for the Device Fingerprint rule: 


1 Linux: Open /opt/novell/nam/idp/conf/tomcat .conf of Identity Server: 


Windows: Go to \Program Files (x86)\Novell\Tomcat\bin. Double click tomcat 7w and 
open the Java tab. 


2 Add the following option: 
JAVA_OPTS="${JAVA_OPTS} -Dcom.microfocus.nam.device. fingerprint .debug=true" 


3 Restart Identity Server. 


NOTE: When the Debug option is enabled, fingerprint data is be shown to all users during login to 
Identity Server. It is recommended to disable this option after debugging is completed. 


Using Logs to Understand How the Device Fingerprint Rule 
Is Evaluated 


If you encounter any error during the Device Fingerprint rule evaluation, check the log files to review 
the error code. The log file location is: 


Linux: /opt/novell/nam/idp/logs/catalina. out 
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Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.1log 
For example, a Device Fingerprint Rule is set up with the following details: 


+ Parameters selected for individual evaluation: Operating System Parameters 
+ Parameters selected for group evaluation: Hardware Parameters, Language Set, User Agent 
+ Parameters in the group must match: 80% 


The following sections include evaluation traces and log entries in different scenarios for this rule: 


¢ Section 30.9.2.1, “A Fingerprint Does Not Exist,” on page 1245 


+ 


Section 30.9.2.2, “Fingerprint Matches,” on page 1246 
Section 30.9.2.3, “Fingerprint Does Not Match,” on page 1246 


Section 30.9.2.4, “When Fingerprint Matches though Some Parameters in the Group Do Not 
Match,” on page 1247 


Section 30.9.2.5, “When Fingerprint Does Not Match as the Evaluation of Group Parameters 
Fails,” on page 1248 


+ 


+ 


+ 


A Fingerprint Does Not Exist 


When a user logs in first time, no fingerprint is available for that device. 
Device Fingerprint Evaluation Trace: 


Evaluating device fingerprint for user: cn=admin, o=novell 
Correlation ID: NA 
Currently fetched device info: 
{"cpuArchitecture": {"cpuArchitecture_cpuArchitecture":"amd64"}, "deviceLanguage": {" 
deviceLanguage_deviceDefaultLanguage": "en- 
US", "deviceLanguage_deviceLanguageSet": "en- 
US,en"}, "navigatorPlatform": {"navigatorPlatform_navigatorPlatform": "Linux 
x86_64"}, "operatingSystem": {"operatingSystem_osVersion":"x86_64", "operatingSystem_ 
osName":"Linux"}, "userAgent": {"userAgent_uaVersion":"39.0", "userAgent_uaName": "Fir 
efox"}, "nonce": "1470327524972", "deviceType": "NA$NA$NA", "dnt": "NA", "navigatorConcur 
rency": "NA", "deviceTouchPoints":"NA","colorDepth":24, } 
Total number of known devices to compare against: 0 
Overall Result: Mismatch 
Failure Cause: No fingerprint or known device found. 
RERREREKRER EERE ERERKEREREERET r ACE End ** 882 eee ee ee SEE RARER A EES 
</amLogEntry> 
<amLogEntry> 2016-08-04T16:18:49Z DEBUG NIDS Application: 
Method: RiskManager.evaluateRisk 
Thread: http-nio-164.99.184.39-8443-exec-4 
DFPRule : false </amLogEntry> 
<amLogEntry> 2016-08-04T16:18:49Z DEBUG NIDS Application: 
Method: RiskManager.evaluateRisk 
Thread: http-nio-164.99.184.39-8443-exec-4 
Rule considered for risk score: DFPRule </amLogEntry> 
<amLogEntry> 2016-08-04T16:18:49Z DEBUG NIDS Application: 
Method: RiskManager.evaluateRisk 
Thread: http-nio-164.99.184.39-8443-exec-4 
traceList: RL~groupName~GeneralGP~ruleCount~1~Success~riskScore~55 
RU~~DFPRule~~negateResult~false~exceptionRule~false~result~false~ 
</amLogEntry> 
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Fingerprint Matches 


When all parameters matches 100%. 
Device Fingerprint Evaluation Trace 


Evaluating device fingerprint for user: cn=admin, o=novell 

Correlation ID: NA 

Currently fetched device info: 

{"cpuArchitecture": {"cpuArchitecture_cpuArchitecture":"amd64"}, "deviceLanguage": {" 
deviceLanguage_deviceDefaultLanguage": "en- 

US", "deviceLanguage_deviceLanguageSet": "en- 

US,en"}, "navigatorPlatform": {"navigatorPlatform_navigatorPlatform": "Linux 
x86_64"}, "operatingSystem": {"operatingSystem_osVersion":"x86_64", "operatingSystem_ 
osName":"Linux"}, "userAgent": {"userAgent_uaVersion":"39.0", "userAgent_uaName": "Fir 
efox"}, "nonce": "1470327774198", "deviceType": "NA$NA$NA", "dnt": "NA", "navigatorConcur 
rency": "NA", "deviceTouchPoints":"NA","colorDepth": 24, } 

Total number of known devices to compare against: 1 

Overall Result: Match 

*eeE**X**** Summary Of comparison against known device************* 

Evaluation Result: Match 

Device Fingerprint: 

{"deviceType": "NASNA$NA", "deviceLanguage_deviceDefaultLanguage": "en- 

US", "userAgent_uaVersion": "39.0", "lastUsageTime" : "1470327529609", "CpuArchitecture_ 
cpuArchitecture":"amd64", "dnt": "NA", "nonce": "1470327524972", "operatingSystem_osVer 
sion": "x86_64", "deviceLanguage_deviceLanguageSet": "en- 

US, en", "userAgent_uaName": "Firefox", "navigatorConcurrency": "NA", "deviceTouchPoints 
":"NA", "navigatorPlatform_navigatorPlatform": "Linux 

x86_64", "colorDepth":"24", "operatingSystem_osName": "Linux"} 

Match Percentage: 100.0 

*eEEK**X****XENG of Comparison against known device*************** 

PERAK EK EERE EAE ERA EEE RARE TT CACO Ende tt tee eR eR EAA ERR EE RAS 

</amLogEntry> 

<amLogEntry> 2016-08-04T16:22:55Z DEBUG NIDS Application: 

Method: RiskManager.evaluateRisk 

Thread: http-nio-164.99.184.39-8443-exec-1 

DFPRule : true </amLogEntry> 

<amLogEntry> 2016-08-04T16:22:55Z DEBUG NIDS Application: 

Method: RiskManager.evaluateRisk 

Thread: http-nio-164.99.184.39-8443-exec-1 

traceList: RL~groupName~GeneralGP~ruleCount~1~Success~riskScore~0 
RU~~DFPRule~~negateResult~false~exceptionRule~false~result~true~ 

</amLogEntry> 


Fingerprint Does Not Match 


When the evaluation on an individual parameter fails. In this example, it is Operating system 
Parameters. 


Device Fingerprint Evaluation Trace 
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30.9.2.4 


Evaluating device fingerprint for user: cn=admin, o=novell 
Correlation ID: NA 
Currently fetched device info: 
{"cpuArchitecture": {"cpuArchitecture_cpuArchitecture":"amd64"}, "deviceLanguage": {" 
deviceLanguage_deviceDefaultLanguage": "en- 
US", "deviceLanguage_deviceLanguageSet": "en- 
US,en"}, "navigatorPlatform": {"navigatorPlatform_navigatorPlatform": "Linux 
x86_64"}, "operatingSystem": {"operatingSystem_osVersion": "x86", "operatingSystem_osN 
ame": "Linux"}, "userAgent": {"userAgent_uaVersion": "39.0", "userAgent_uaName":"Firefo 
x"}, "webg1Data": {}, "nonce": "1470328154673", "deviceType": "NASNA$NA", "dnt": "NA", "nav 
igatorConcurrency": "NA", "deviceTouchPoints":"NA", "colorDepth": 24} 
Total number of known devices to compare against: 1 
Overall Result: Mismatch 
*RAEKAAX***** Summary Of comparison against known device************* 
Evaluation Result: Mismatch 
Device Fingerprint: 
{"deviceType": "NASNA$NA", "deviceLanguage_deviceDefaultLanguage": "en- 
US", "userAgent_uaVersion": "39.0", "lastUsageTime" : "1470328017123", "CpuArchitecture_ 
cpuArchitecture":"amd64", "dnt": "NA", "nonce": "1470328016641", "operatingSystem_osVer 
sion": "x86_64", "deviceLanguage_deviceLanguageSet": "en- 
US, en", "userAgent_uaName": "Firefox", "navigatorConcurrency":"NA", "deviceTouchPoints 
":"NA", "navigatorPlatform_navigatorPlatform": "Linux 
x86_64", "colorDepth": "24", "operatingSystem_osName": "Linux"} 
Failure Cause: At least one mandatory attribute failed match/is unavailable. 
Offending Mandatory Attribute: operatingSystem_osVersion 
KREEKKAKEEEX***EN of comparison against known device*************** 
ARK ERK KEES ERLE REREEREEEAT CACO Eee eRe RARE RARER RK KS 
</amLogEntry> 
<amLogEntry> 2016-08-04T16:29:36Z DEBUG NIDS Application: 
Method: RiskManager.evaluateRisk 
Thread: http-nio-164.99.184.39-8443-exec-1 
DFPRule : false </amLogEntry> <amLogEntry> 2016-08-04T16:29:36Z DEBUG NIDS 
Application: 
Method: RiskManager.evaluateRisk 
Thread: http-nio-164.99.184.39-8443-exec-1 
Rule considered for risk score: DFPRule </amLogEntry> 
<amLogEntry> 2016-08-04T16:29:36Z DEBUG NIDS Application: 
Method: RiskManager.evaluateRisk 
Thread: http-nio-164.99.184.39-8443-exec-1 
traceList: RL~groupName~GeneralGP~ruleCount~1~Success~riskScore~55 
RU~~DFPRule~~negateResult~false~exceptionRule~false~result~false~ 
</amLogEntry> 


When Fingerprint Matches though Some Parameters in the Group 
Do Not Match 


When the group parameters do not match 100%, but meet the match criteria specified in the rule. 


Device Fingerprint Evaluation Trace 
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30.9.2.5 


Evaluating device fingerprint for user: cn=admin, o=novell 

Correlation ID: NA 

Currently fetched device info: 

{"availFontSet": {}, "cpuArchitecture": {"cpuArchitecture_cpuArchitecture":"amd64"}," 
deviceLanguage": {"deviceLanguage_deviceDefaultLanguage": "en- 

US", "deviceLanguage_deviceLanguageSet": "en- 

US, en"}, "html5DataSet": {}, "navigatorPlatform": {"navigatorPlatform_navigatorPlatfor 
m": "Linux 

x86_64"}, "operatingSystem": {"operatingSystem_osVersion":"x86_64", "operatingSystem_ 
osName":"Linux"}, "screenResolution": {}, "userAgent": {"userAgent_uaVersion":"39,.1"," 
userAgent_uaName":"Firefox"}, "webglData": {}, "nonce": "1470328282330", "deviceType":" 
NASNA$NA", "dnt": "NA", "navigatorConcurrency": "NA", "deviceTouchPoints": "NA", "colorDe 
pth":24,"headerSet": {}, "userDN": {}, "clientIP": {}} 

Total number of known devices to compare against: 1 

Overall Result: Match 

*REEK*AX***** Summary Of comparison against known device************* 

Evaluation Result: Match 

Device Fingerprint: 

{"deviceType": "NASNA$NA", "deviceLanguage_deviceDefaultLanguage": "en- 

US", "userAgent_uaVersion": "39.0", "lastUsageTime" : "1470328017123", "CpuArchitecture_ 
cpuArchitecture":"amd64", "dnt": "NA", "nonce": "1470328016641", "operatingSystem_osVer 
sion":"x86_64", "deviceLanguage_deviceLanguageSet" : "en- 

US, en", "userAgent_uaName": "Firefox", "navigatorConcurrency":"NA", "deviceTouchPoints 
":"NA", "navigatorPlatform_navigatorPlatform": "Linux 

x86_64", "colorDepth": "24", "operatingSystem_osName": "Linux"} 

Match Percentage: 85.71429 

Mismatching Flexible Attributes: [userAgent_uaVersion] 

KREEKKAKEEEE***EN of Comparison against known device*************** 

REBAR AAA ER ES ERA CRIES AOR aC End 2 * 242 2* 222A KEELER EERE 

</amLogEntry> 

<amLogEntry> 2016-08-04T16:31:39Z DEBUG NIDS Application: 

Method: RiskManager.evaluateRisk 

Thread: http-nio-164.99.184.39-8443-exec-2 

DFPRule : true </amLogEntry> 

<amLogEntry> 2016-08-04T16:31:39Z DEBUG NIDS Application: 

Method: RiskManager.evaluateRisk 

Thread: http-nio-164.99.184.39-8443-exec-2 

traceList: RL~groupName~GeneralGP~ruleCount~1~Success~riskScore~0 
RU~~DFPRule~~negateResult~false~exceptionRule~false~result~true~ 

</amLogEntry> 


When Fingerprint Does Not Match as the Evaluation of Group 


Parameters Fails 


When the group parameters does not match the criteria as specified in the rule. 


Device Fingerprint Evaluation Trace 
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30.10 


Evaluating device fingerprint for user: cn=admin, o=novell 

Correlation ID: NA 

Currently fetched device info: 

{"availFontSet": {}, "cpuArchitecture": {"cpuArchitecture_cpuArchitecture":"amd64"}," 
deviceLanguage": {"deviceLanguage_deviceDefaultLanguage" : "en- 

US", "deviceLanguage_deviceLanguageSet": "en- 

US"}, "htm15DataSet": {}, "navigatorPlatform": {"navigatorPlatform_navigatorPlatform": 
"Linux 

x86"}, "operatingSystem": {"operatingSystem_osVersion":"x86_64", "operatingSystem_osN 
ame": "Linux"}, "screenResolution": {}, "userAgent": {"userAgent_uaVersion":"39.0","use 
rAgent_uaName":"Firefox"}, "webglData": {}, "nonce": "1470328761567", "deviceType": "NA$ 
NASNA", "dnt": "NA", "navigatorConcurrency": "NA", "deviceTouchPoints":"NA", "colorDepth 
":24,"headerSet": {}, "userDN": {},"CclientIP": {}} 

Total number of known devices to compare against: 1 

Overall Result: Mismatch 

*REEK*AE***** Summary Of comparison against known device************* 

Evaluation Result: Mismatch 

Device Fingerprint: 

{"deviceType": "NASNA$NA", "deviceLanguage_deviceDefaultLanguage": "en- 

US", "userAgent_uaVersion": "39.1", "lastUsageTime" : "1470328521354", "CcpuArchitecture_ 
cpuArchitecture":"amd64", "dnt": "NA", "nonce": "1470328503258", "operatingSystem_osVer 
sion": "x86_64", "deviceLanguage_deviceLanguageSet" : "en- 

US, en", "userAgent_uaName": "Firefox", "navigatorConcurrency": "NA", "deviceTouchPoints 
":"NA", "navigatorPlatform_navigatorPlatform": "Linux 

x86", "colorDepth":"24", "operatingSystem_osName": "Linux"} 

Failure Cause: Flexible attributes percentage match is lesser than threshold. 
Match Percentage: 71.42857 

Mismatching Flexible Attributes: [userAgent_uaVersion, 
deviceLanguage_deviceLanguageSet ] 

KREEKKAREEEX**EOG of comparison against known device*************** 
REKKERERERAAELKE KAA KR RERKERT HACE Enid 22 28 eRe ee ES Ae RES Re 

</amLogEntry> 

<amLogEntry> 2016-08-04T16:39:51Z DEBUG NIDS Application: 

Method: RiskManager.evaluateRisk 

Thread: http-nio-164.99.184.39-8443-exec-2 

DFPRule : false </amLogEntry> 

<amLogEntry> 2016-08-04T16:39:51Z DEBUG NIDS Application: 

Method: RiskManager.evaluateRisk 

Thread: http-nio-164.99.184.39-8443-exec-2 

Rule considered for risk score: DFPRule </amLogEntry> 

<amLogEntry> 2016-08-04T16:39:51Z DEBUG NIDS Application: 

Method: RiskManager.evaluateRisk 

Thread: http-nio-164.99.184.39-8443-exec-2 

traceList: RL~groupName~GeneralGP~ruleCount~1~Success~riskScore~55 
RU~~DFPRule~~negateResult~false~exceptionRule~false~result~false~ 

</amLogEntry> 


Troubleshooting Advanced Session Assurance 


¢ Section 30.10.1, “Troubleshooting Using the Log Files,” on page 1250 
¢ Section 30.10.2, “Important Error Messages,” on page 1254 
¢ Section 30.10.3, “Checking Session Assurance Configuration Details,” on page 1255 


NOTE: If any critical issue happens, you can disable Advanced Session Assurance for the specific 
URLs and user-agents. For information about how to disable Advanced Session Assurance, see 
“Disabling Advanced Session Assurance” on page 937. 
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30.10.1 Troubleshooting Using the Log Files 


The following are the locations of log files: 
Identity Server: 


You must select Echo to Console (Devices > Identity Servers > Edit > Auditing and Logging) to 
enable logging to these files. 


Linux: /var/opt/novell/nam/logs/idp/tomcat/catalina.out 
Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout.1log 
Access Gateway ESP: 

Linux: /var/opt/novell/nam/logs/mag/tomcat/catalina.out 
Windows: \Program Files\Novell\Tomcat\logs\stdout .1log 
Access Gateway: 

Linux: /var/log/novell-apache2/error_log 

Windows: \Program Files\Novell\Apache\logs\error.1log 


¢ Section 30.10.1.1, “Using Logs,” on page 1250 
¢ Section 30.10.1.2, “Using debug Logs,” on page 1251 


30.10.1.1 Using Logs 


For basic troubleshooting, enable the severe log level for Identity Server and Access Gateway ESP 
and the crit log level for Access Gateway. 


Access Gateway: 


1 Click Devices > Access Gateways > Edit > Advanced Options. 
2 Add the following: 


LogLevel crit 
Identity Server: 


1 Click Devices > Identity Servers > Edit > Auditing and Logging. 
2 Select File Logging and Echo to Console. 


3 Under Component File Logger Levels > Application, select severe. 
If you want advanced troubleshooting, enable the debug level. See “Using debug Logs” on 
page 1251. 
Sample log messages when Session Assurance fails: 
These log snippets provide the following information: 


+ User DN 

¢ Correlation ID (session ID) 

¢ Currently fetched device information 

¢ Device Fingerprint (Device fingerprint stored in the session) 
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30.10.1.2 


e Result 
¢ Failure cause 
¢ Offending Mandatory Attribute (information about the parameter that did not match) 


Identity Server 


<amLogEntry> 2016-09-23T09:59:06Z SEVERE NIDS Application: 

eeKKKKKEEEE**Dayice Fingerprint Evaluation Trace************* 

Evaluating device fingerprint for user: cn=admin, o=novell 

Correlation ID: d2ee43e3fbb2ca0487c9088fbc14c64cae552ecf6233412aa73Fe6758a329598 
Currently fetched device info: {"headerSet": {"user-agent":"Microsoft Office 
Protocol Discovery"}} 

Total number of known devices to compare against: 1 

Overall Result: Mismatch 


*REAK*AX*****Summary Of comparison against known device************* 


Evaluation Result: Mismatch 

Device Fingerprint: {"user-agent":"Mozilla/5.0 (X11; Linux x86_64; rv:39.0) 
Gecko/20100101 Firefox/39.0"} 

Failure Cause: At least one individual attribute failed match/is unavailable. 
Offending individual attribute: user-agent 
KHHKKKKKKXEX*X*E OG of Comparison against known device*************** 


RRKKKEKEKEKEE RRR EEEEKEEERERET COG Enid? * 4 48 ee RES EAS ERER ERE ERS 


</amLogEntry> 


<amLogEntry> 2016-09-23T09:59:06Z SEVERE NIDS Application: The session might have 
been hijacked. Logging out 
</amLogEntry> 


Access Gateway 


The following is a snippet of the log when the crit level is enabled. This log records the session 
assurance failure message: 


Sep 28 20:27:07 namiso httpd[9797]: [crit] AM#104600404 AMDEVICEID#ag- 
8B62635F46CD2776: 
AMAUTHID#965dce7b7f4963730f edObebf93d4ef 70e062Fb90e590569729F 2b9b9dFd: 
AMEVENTID#23: logging out user with DN=cn=admin, o=novell and session ID 
=965dce7b7f4963730f edObebf93d4ef 70e062Fb90e590569729F2b9b9dfd because of session 
assurance mismatch 


Using debug Logs 


Debug logs include detailed information such as reason of failure, list of parameters and session 
interval value. 


Perform the following steps to enable logging at the debug level: 
Access Gateway: 


1 Click Devices > Access Gateways > Edit > Advanced Options. 
2 Add the following line: 


LogLevel debug 
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Identity Server: 


1 Click Devices > Identity Servers > Edit > Auditing and Logging. 
2 Select File Logging and Echo to Console. 
3 Under Component File Logger Levels > Application, select debug. 


Sample log messages generated at the debug log level when Session 
Assurance fails: 


Device Fingerprint Evaluation Trace for Identity Server 
This log snippet provides the following information: 


+ User DN 

e Correlation ID (session ID) 

¢ Currently fetched device information 

+ Device Fingerprint (Device fingerprint stored in the session) 

e Result 

¢ Failure cause 

+ Offending Mandatory Attribute (information about the parameter that did not match) 
¢ List of parameters being considered in the fingerprinting 


*RHKKKEEEEE**Dayice Fingerprint Evaluation Trace************* 


Evaluating device fingerprint for user: cn=admin, o=novell 

Correlation ID: CFOE200CA9FB92A3F29D79560140526E 

Currently fetched device info: 

{"availFontSet": {}, "cpuArchitecture": {"cpuArchitecture_cpuArchitecture":"amd64"}," 
deviceLanguage": {"deviceLanguage_deviceLanguageSet": "en- 

US, en", "deviceLanguage_deviceDefaultLanguage" : "en- 

US"}, "htm15DataSet": {}, "navigatorPlatform": {}, "operatingSystem": {"operatingSystem_ 
osName": "Windows", "operatingSystem_osVersion":"7"},"screenResolution": {}, "userAgen 
t":{}, "webglData": {}, "nonce": "1470635556957", "deviceType": "NA$NA$NA", "deviceTouchP 
oints":0,"colorDepth":24, "headerSet": {}, "userDN": {}, "clientIP": {}} 

Total number of known devices to compare against: 1 

Overall Result: Mismatch 


ReRKEEE******SUmmMary Of comparison against known device************* 


Evaluation Result: Mismatch 
Device Fingerprint: 
{"deviceType": "NA$NA$NA", "deviceLanguage_deviceLanguageSet":"en- 
US, en, af", "deviceLanguage_deviceDefaultLanguage": "en- 
US", "deviceTouchPoints":"0", "cpuArchitecture_cpuArchitecture":"amd64","colorDepth" 


1252 Troubleshooting 


"24", "nonce":"1470635480882", "operatingSystem_osName": "Windows", "operatingSystem_ 
osVersion":"7"} 
Failure Cause: Atleast one mandatory attribute failed match/is unavailable. 
Offending Mandatory Attribute: deviceLanguage_deviceLanguageSet 


KRHKKKKKKXEX***E OG of Comparison against known device*************** 


REEL RE AER ERE EREREET FOG Enid 22 244% 3% 2 RRA RRR EE RRA A ERE 


</amLogEntry> 


<amLogEntry> 2016-08-08T05:52:39Z SEVERE NIDS Application: Session seems to have 
got hijacked so logout! Trying to forcefully log out session 
CFOE200CA9FB92A3F29D79560140526E. Root cause: error during evaluating fingerprint. 
Evaluated nonce is null 


Device Fingerprint Evaluation Trace for Access Gateway 


Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
O95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: configuring session assurance policy 
Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: session assurance is enabled 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: trigger time =1 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: list of attributes enabled for session 
assurance... 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: server side finger print=clientip 
Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
colorDepth 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
Q5F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
cpuArchitecture_cpuArchitecture 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
deviceTouchPoints 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
O5F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
deviceTouchSupport 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
Q5F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
deviceType 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
deviceLanguage_deviceLanguageSet 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
Q5F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
deviceLanguage_deviceDefaultLanguage 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
operatingSystem_osName 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance 
operatingSystem_osVersion 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: server side finger print=user -agent 
Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
Q5F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
timezoneOffset 
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30.10.2 


30.10.2.1 


30.10.2.2 


Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = dnt 
Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
O95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
navigatorConcurrency 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
navigatorPlatform_navigatorPlatform 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
userAgent_uaName 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
Q5F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
userAgent_uaVersion 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
html5DataSet_html5AvData 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = 
availFontSet_availableFonts 

Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: advanced session assurance = webglData 
Sep 29 18:03:05 lsb httpd[30697]: [info] AM#504600000 AMDEVICEID#ag- 
95F88CA3CFF470ED: AMAUTHID#: AMEVENTID#8568: session assurance policy configured 
successfully 


Important Error Messages 


The following sections include important error messages along with required actions: 
e Section 30.10.2.1, “Cookie mismatch. The session might have been hijacked. Logging out 
session <session|ID>,” on page 1254 


¢ Section 30.10.2.2, “Nonce has been used already. Possible replay attack. Logging out the 
session <session|ID>,” on page 1254 


¢ Section 30.10.2.3, “Fingerprint evaluation failed. The session might have been hijacked. Logging 
out the session <sessionID>,” on page 1255 


Cookie mismatch. The session might have been hijacked. Logging 
out session <sessionID> 


This message is logged when the session might have been hijacked. If the session is intact and still 
you get this error, contact the technical support team with debug logs. 


Nonce has been used already. Possible replay attack. Logging out 
the session <sessionID> 


This message is logged when the session might have hijacked. Contact the technical support team 
with debug logs and login again. 
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30.10.2.3 


30.10.3 


Fingerprint evaluation failed. The session might have been hijacked. 
Logging out the session <sessionID> 


Check the log to see what error occurred. Mostly, this message is logged when the fingerprint does 
not match. 


For example, you will see the following mismatch error when language settings do not match during a 
user session. This might be due to session hijacking as language settings would not match when two 
different users are trying to access the same session from separate devices. 


Checking Session Assurance Configuration Details 


You can check the configuration details in the debug log files. In the catalina.out or stdout . log, 
you can check whether Session Assurance is initialized, what parameters are enabled, and the time- 
frequency. The log file captures first request and further evaluation after login exceeds time interval. 


If an error occurs while initializing Session Assurance, it gets disabled. 
Example Log Snippets 
Information about whether Session Assurance is enabled: 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 
Method: NIDPSessionAssurance. initializeFPConfiguration 
Thread: RMI TCP Connection(1)-127.0.0.1 

Session assurance enabled true 

</amLogEntry> 


Information about whether Session Assurance initialized 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 

Method: NIDPSessionAssurance. initializeExcludeListSetting 

Thread: RMI TCP Connection(1)-127.0.0.1 

Session Assurance : User Agent Exclude list [NMA_Auth] </amLogEntry> 


Session Assurance IDC cookie grace period is 20 seconds 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 
Method: NIDPSessionAssurance.getNidpConfigPropertyInt 
Thread: RMI TCP Connection(1)-127.0.0.1 


Property read from edirectory configuration store -------- > Property:SESSION 
ASSURANCE IDC COOKIE GRACEPERIOD Value: 20 
</amLogEntry> 


Session Assurance interval is 1.0 minute 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 
Method: NIDPSessionAssurance.initializeFPConfiguration 
Thread: RMI TCP Connection(1)-127.0.0.1 

Session assurance interval 1.Qminutes 

</amLogEntry> 
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Parameters being evaluated in the fingerprint are Client IP, User-agent, Hardware Parameters, 
Operating System, Screen Resolution and TimeZone Offset. 


Session assurance plan <?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<FingerprintConfiguration Enabled="true" ID="IDP" TriggerTimer="1" 
MatchLevel="100"> 

<PropertyParams PropertyName="ClientIP" PropertyRequired="true"/> 

<PropertyParams PropertyName="colorDepth" PropertyRequired="true"/> 

<PropertyParams PropertyName="cpuArchitecture_cpuArchitecture" 
PropertyRequired="true"/> 

<PropertyParams PropertyName="deviceTouchPoints" PropertyRequired="true"/> 

<PropertyParams PropertyName="deviceType" PropertyRequired="true"/> 

<PropertyParams PropertyName="operatingSystem_osName" PropertyRequired="true"/ 
> 

<PropertyParams PropertyName="operatingSystem_osVersion" 
PropertyRequired="true"/> 

<PropertyParams PropertyName="user-agent" PropertyRequired="true"/> 

<PropertyParams PropertyName="ScreenResolution_availableScreenResolution" 
PropertyRequired="true"/> 

<PropertyParams PropertyName="ScreenResolution_screenResolution" 
PropertyRequired="true"/> 

<PropertyParams PropertyName="timezoneOffset" PropertyRequired="true"/> 
</FingerprintConfiguration> 
</amLogEntry> 


List of server-side parameters: Client IP and User Agent 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 

Method: NIDPSessionAssurance.initializeFPConfiguration 

Thread: RMI TCP Connection(1)-127.0.0.1 

Server Side Fingerprint Attributes [clientIP, user-agent] </amLogEntry> 


List of client-side parameters: Hardware Parameters, Operating System Parameters, Screen 
Resolution, Time Zone Offset 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 

Method: NIDPSessionAssurance.initializeFPConfiguration 

Thread: RMI TCP Connection(1)-127.0.0.1 

Client Side Fingerprint Attributes [colorDepth, cpuArchitecture_cpuArchitecture, 
deviceTouchPoints, deviceType, operatingSystem_osName, operatingSystem_osVersion, 
screenResolution_availableScreenResolution, screenResolution_screenResolution, 
timezoneOffset] </amLogEntry> 


Information about whether exclude has been configured for any resource 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 

Method: NIDPSessionAssurance.getNidpConfigPropertyString 

Thread: RMI TCP Connection(1)-127.0.0.1 

Property read from edirectory configuration store -------- > Property:SESSION 
ASSURANCE USER AGENT REGEX EXCLUDE LIST Value: Android 4\. </amLogEntry> 


<amLogEntry> 2016-09-06T19:19:34Z DEBUG NIDS Application: 

Method: NIDPSessionAssurance. initializeExcludeListSetting 

Thread: RMI TCP Connection(1)-127.0.0.1 

Session Assurance : User Agent Regex Exclude list [Android 4\.] </amLogEntry> 
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Troubleshooting XML Validation Errors on Access 
Gateway Appliance 


An XML validation error is often ignored because the returning message does not appear to be 
serious. However, closer inspection of Access Gateway Appliance shows that none of the changes 
have been applied. When a change is applied by using UI, the system writes the configuration data to 
the configuration store on Administration Console and to the /opt/novell/nam/mag/webapps/agm/ 
WEB-INF/config/current/config.xml file on Access Gateway Appliance. If this file passes the 
schema checks on Access Gateway Appliance, the /opt/novell/nam/mag/webapps/agm/WEB- INF/ 
config/pending/xxxx-config. xml file (where xxx is the transaction|ID) is updated with the 
configuration. 


This is the file that Access Gateway Appliance reads when it loads or refreshes. If the config. xml 
file from /opt/novell/nam/mag/webapps/agm/WEB-INF/config/current and /opt/novell/nam/ 
mag/webapps/agm/WEB- INF/config/pending/ are not in sync, then all changes you defined have 
not been applied to Access Gateway Appliance. 


You need to pay attention to XML validation errors and identify the key steps required to solve such 
problems. There are two main scenarios that are discussed in this section: 


¢ Section 30.11.1, “Modifying a Configuration That References a Removed Object,” on page 1257 


¢ Section 30.11.2, “Configuration UI Writes Incorrect Information to the Local Configuration Store,” 
on page 1259 


Modifying a Configuration That References a Removed 
Object 

One scenario that causes the XML validation errors is when a configuration references an object that 
has been removed. For example, a custom authentication contract was created and assigned to a 
protected resource. The contract was manually deleted from Identity Server configuration, but Access 
Gateway protected resource still references it, even though it is not displayed in the user interface. 


After you identify the missing link, you can use the Access Manager interface to work around the 
problem. 


To troubleshoot this scenario: 


1 Search the /opt/novell/devman/share/logs/app_sc.0.1log file on Administration Console 
server for #200904025: Error - XML VALIDATION FAILED. 


After you find the entry, work backwards to identify the start of the Java exception. Locate the 
problem strings or entry from the configuration, such as the following string 
authprocedure_NEIL___Name_Password___Form found in the following entry: 


871(D)Wed May 23 15:45:06 BST 


2007(L)webui.sc(T)26(C)com.volera.vcdn.webui.sc.dispatcher .ConfigworkDispatche 
r(M)A(E)org.jdom.input.JDOMParseException: Error on 

line 1120: cvc-id.1: There is no ID/IDREF binding for IDREF 
‘authprocedure_NEIL___Name_Password___Form'. 


at org.jdom. input .SAXBuilder .build(SAXBuilder . java: 468) 
at org.jdom. input .SAXBuilder .build(SAXBuilder.java:770) 
at com.volera.vcdn.platform.util.XmlUtil.validateXML(y:3304) 


at com.volera.vcdn.webui.sc.dispatcher .ConfigworkDispatcher .A(y:793) 
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at com.volera.vcdn.webui.sc.dispatcher .ConfigworkDispatcher .do_deviceCon 


fig(y:648) 


at org.apache.coyote.http11.Http11Processor.process(HttpiiProcessor.java :799) 
at org.apache.coyote.http11.Httpi11Protocol$Http1iConnectionHandler.proce 
ssConnection(Http11Protocol. java: 705) 


at org.apache.tomcat.util.net.TcpWorkerThread.runIt(PoolTcpEndpoint.java :577) 


at 
org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool. java: 
683) 


at java.lang. Thread. run(Thread. java: 534) 


(Msg)<amLogEntry> 2007-05-23T15:45:06Z ERROR DeviceManager: AM#200904025: 
Error 


- XML VALIDATION FAILED. PLEASE CHECK APP_SC LOG </amLogEntry> 


2 On Access Gateway Appliance, change to the /opt/novell/nam/mag/webapps/agm/WEB- INF/ 
config/current directory and open the config. xml file. Search for the problem string and the 
corresponding protected resource. 


The example below shows that the problem string is tied to the 
ProtectedResourceID_svhttp_mylag_iMon_root resource. This maps to the HTTP reverse 
proxy called mylag, the service called iMon, and the protected resource called root. 


----- snippet from problem area of config.xml ------ 
<ProtectedResource Name="root" Enable="1" Description="" 
LastModified="116973455 
5995" LastModifiedBy="cn=admin, o=novell" 
UserInterfaceID="ProtectedResourceID_sv 
http_mylag_iMon_root" 
ProtectedResourceID="ProtectedResourceID_svhttp_mylag_iMon 
root"> 


<URLPathList LastModified="4294967295" LastModifiedBy="String"> 
<URLPath URLPath="/*" UserInterfaceID="/*"/> 
</URLPathList> 
<PolicyEnforcementList LastModified="1168947602067" 
schemaVersion="1.34" 
LastModifiedBy="cn=admin, o=novell" 
RuleCombiningAlgorithm="DenyOverrideswithPri 


ority"> 


<PolicyRef ElementRefType="ExternalWithIDRef" 
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ExternalDocRef="0u=xpem1PEP, ou=mastercdn, ou=ContentPublisherContainer, ou=Parti 
tion, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, o=novell:ro 
maContentCollectionXMLDoc" 
UserInterfaceID="PolicyID_xpem1PEP_AGFormFill_1168947167634" 
ExternalElementRef="PolicyID_xpem1PEP_AGFormFill_1168947167634"/> 


</PolicyEnforcementList> 


<AuthenticationProcedureRef 
AuthProcedureIDRef="authprocedure_NEIL___Name_Password___Form"/> 


</ProtectedResource> 


----- end of snippet from problem area of config.xml ------ 


3 Look atthe AuthenticationProcedureRef variable, which points to the contract assigned to 
the protected resource. You can see that the authprocedure_NEIL___Name_Password___ Form 
contract is assigned to it. 


However, when you look at Access Gateway Appliance configuration in Administration Console, 
you can see that the assigned contract is [None], which is not the contract shown in the 
example. Change it to another contract name, apply the change, then set the contract back to 
[None] to clear the problem entry. The setup now operates with no XML validation errors. 


Configuration UI Writes Incorrect Information to the Local 
Configuration Store 


In this scenario, you apply the same change twice in quick succession, and the information written to 
the configuration store is invalid. Subsequent schema checks detect this invalid configuration and 
return an XML validation error. This scenario is more complex because it involves changing the 
configuration store on Administration Console. 


Troubleshooting Steps 


1 On Administration Console, search the /opt/novell/devman/share/logs/app_sc.0.1og file 
for #200904025: Error - XML VALIDATION FAILED. 


After you find the entry, work backwards to identify the start of the Java exception. From this, 
locate the problem strings or entry from the configuration, such as 
ProtectedResourceID_svhttp_sjh_portal_sjh_portal_1179933619340. This message also 
indicates that a defined protected resource might not be unique. The configuration shows that 
before the Java exception, there is not enough information to narrow down the problem, so more 
troubleshooting is required. 


The following is a snippet from the problem area of app_sc.0.1og file that indicates that there 
are multiple occurrences of a protected resource. 
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Caused by: org.xml.sax.SAXParseException: cvc-id.2: There are multiple 
occurrences of ID value 
'ProtectedResourceID_svhttp_sjh_portal_sjh_portal_1179933619340'. 

at org.apache.xerces.util.ErrorHandlerwrapper .createSAxXParseException(Unknown 
Source) 

at org.apache.xerces.util.ErrorHandlerwrapper.error(Unknown Source) 

at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source) 
at org.apache.xerces.parsers.XMLParser.parse(Unknown Source) 

at org.apache.xerces.parsers.AbstractSAxParser.parse(Unknown Source) 
at org.jdom. input .SAXBuilder .build(SAXBuilder.java: 453) 

at org.jdom. input .SAXBuilder .build(SAXBuilder.java:770) 

at com.volera.vcdn.platform.util.XmlUtil.validateXML(y:3304) 

at com.volera.vcdn.webui.sc.dispatcher .ConfigworkDispatcher .A(y:793) 


Boies EA EE RE EI tee Geek patches come E nee 
7 sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) 

E A EE A E P E pene AE E 
sun reflect „belegatingHethodaccessor npl invoke (DelegatingethodAccessortmp].j 
ava:25 


at java.lang.reflect.Method.invoke(Method.java:324) 

at com.volera.vcdn.webui.sc.dispatcher .DefaultDispatcher .invoke(y:469) 

at 
com.volera.vcdn.webui.sc.dispatcher .DefaultDispatcher .processRequest (y:1732) 
at com.volera.roma.app.handler .DispatcherHandler .processRequest (y:3168) 

at com.volera.roma.servlet.GenericController.doPost(y:53) 

at javax.servlet.http.HttpServlet.service(HttpServlet.java:716) 

at javax.servlet.http.HttpServlet.service(HttpServlet.java:809) 

at 
org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFi 
lterChain.java:200) 

at 
org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChai 
n.java:146) 

at 
org.apache.catalina.core.StandardPipeline$StandardPipelineValveContext.invokeN 
ext(StandardPipeline.java:594) 

at com.novell.accessmanager .tomcat .SynchronizationValve.invoke(y:297) 

at org.apache.catalina.core.StandardPipeline.invoke(StandardPipeline.java:433) 
at org.apache.catalina.core.ContainerBase.invoke(ContainerBase.java:948) 

at org.apache.coyote.tomcat5.CoyoteAdapter .service(CoyoteAdapter .java:152) 

at 
org.apache.coyote.http11.Http11Protocol$Http11ConnectionHandler .processConnect 
ion(Http11Protocol.java:705) 

at 
org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool. java: 
683) 

at java.lang.Thread.run(Thread.java:534) 

(Msg)<amLogEntry> 2007-05-23T13:22:15Z ERROR DeviceManager: AM#200904025: 
Error - XML VALIDATION FAILED. PLEASE CHECK APP_SC LOG </amLogEntry> 


2 Confirm that the change has not been applied at Access Gateway Appliance: 


2a In Administration Console Dashboard, select Devices > Access Gateways > Edit > 
Advanced Options and add the following line: 


LogLevel debug 
2b Click OK and then update Access Gateways. 
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For more information about Access Gateway log, see Section 21.4.1, “Managing Access 
Gateway Logs,” on page 1048. 


2c Search for in-memory errors in the error_log file. When these errors are displayed, the 
working Access Gateway Appliance configuration has not been updated with the latest 
changes. 


2d Identify the protected resource with these issues. In the following case, the protected 
resource is the same, so you must look at the config.xm1 file and search for this specific 
protected resource. For example: 


May 23 13:22:14 chw-amtlag1-176 : 404502 ©: 7168: 0: 0: 
VcpConfiguration::reconfigure starting AafLog 
May 23 13:22:14 chw-amtlag1-176 : 404502 ©: 7168: 0: 0: 
VcpConfiguration: :reconfigure finished 
Error at file "in-memory", line 328, column 306 

Message: Datatype error: Type:InvalidDatatypeValueException, Message:ID 
"ProtectedResourceID_svhttp_sjh_portal_sjh_portal_1179933619340' is not 
unique. 
ERROR: Error retrieving config.xml: No data available 


3 Search for the preceding string in the /opt/novell/nam/mag/webapps/agm/WEB- INF/config/ 
current/config. xml file. You should see the following type of information: 


<ProtectedResourceList> 
<ProtectedResource Name="sjh_redirect" Enable="1" 
Description="""LastModified="1179934022767" 


LastModifiedBy="cn=admin, o=novell"UserInterfaceID="ProtectedResourceID_svhttp_ 
sjh_portal_sjh_portal_1179933619340" 
ProtectedResourceID="ProtectedResourceID_svhttp_sjh_portal_sjh_portal_11799336 
19340"> 
<URLPathList LastModified="4294967295" LastModifiedBy="String"> 

<URLPath URLPath="/*" UserInterfaceID="/*"/> 

</URLPathList> 

<PolicyEnforcementList LastModified="1179934011081" schemaVersion="0.1" 
LastModifiedBy="cn=admin, o=novell" 
RuleCombiningAlgorithm="DenyOverrideswithPriority" 
IncludedPolicyCategories=""/> 

<AuthenticationProcedureRef 
AuthProcedureIDRef="authprocedure_Name_Password___Form"/> 

</ProtectedResource> 

</ProtectedResourceList> 


You should also see the following information: 
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<ProtectedResourceList LastModified="1179949051828" 
LastModifiedBy="cn=admin, o=novell"> 
<ProtectedResource Name="sjh_redirect" Enable="1" Description="" 
LastModified="1179949051828" LastModifiedBy="cn=admin, o=novell" 
UserInterfaceID="ProtectedResourceID_svhttp_sjh_portal_sjh_portal_117993361934 
9" 
ProtectedResourceID="ProtectedResourceID_svhttp_sjh_portal_sjh_portal_11799336 
19340"> 
<URLPathList LastModified="4294967295" LastModifiedBy="String"> 
<URLPath URLPath="/*" UserInterfaceID="/*"/> 
</URLPathList> 
<PolicyEnforcementList LastModified="1179949047445" schemaVersion="0.1" 
LastModifiedBy="cn=admin, o=novell" 
RuleCombiningAlgorithm="DenyOverrideswithPriority" 
IncludedPolicyCategories=""> 
<PolicyRef ElementRefType="ExternalWithIDRef" 
ExternalDocRef="0u=xpem1PEP, ou=mastercdn, ou=ContentPublisherContainer, ou=Parti 
tion, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, o=novell:ro 
maContentCollectionXMLDoc" 
UserInterfaceID="PolicyID_xpem1PEP_AGAuthorization_1176770874051" 
ExternalElementRef="PolicyID_xpem1PEP_AGAuthorization_1176770874051"/> 
</PolicyEnforcementList> 
<AuthenticationProcedureRef 
AuthProcedureIDRef="authprocedure_Name_Password___Form"/> 
</ProtectedResource> 
</ProtectedResourceList> 


This is the duplicate entry that is causing the problem. You need to clear one of the entries from 
the configuration. If you clear it from the /opt/novell/nam/mag/webapps/agm/WEB- INF/ 
config/current/config. xml file, then any change applied in the UI rewrites the information to 
the config. xml file. 


4 Remove the duplicate entry from Administration Console server's configuration store. To do this, 
you need an LDAP browser. 


You can download a free Java-based tool from the Internet. 


4a Start the LDAP browser, then locate the ag-xxxx that matches Access Gateway Appliance 
you are having problems with. 


The easiest way is to go to the Auditing > General Logging tab of the Access Manager 
Administration Console and identify your Access Gateway Appliance ID. This ID 
corresponds to the first four digits of the ag-xxxx in the LDAP browser. 


4b Click the ag-xxxx container. You should see CurrentConfig and WorkingConfig containers 
within this Access Gateway container. 


4c Select the CurrentConfig, then the RomaAGConfigurationXMLDoc attribute. Copy and paste 
the attribute value into any editor. This is the configuration from the LAG. 


4d Search for the RomaAGConfigurationXMLDoc attribute string and remove the entire section 
on one of the hits starting with <ProtectedResourceList> and ending with </ 
ProtectedResourceList>. 


4e Select and save the modified text. 
4f Paste the saved text into the RomaAGConfigurationXMLDoc attribute value. 


4g Repeat these steps for the RomaAGConfigurationXMLDoc attribute in WorkingConfig, and 
remove the duplicate entry that is causing the XML validation errors. 


5 Restart Tomcat on Administration Console machine. 


6 Log in to Administration Console again. Make a small change to the setup and apply that 
change, and verify that the XML validation error has disappeared. 
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30.12 Troubleshooting OAuth and OpenID Connect 


This section discusses the following issues and workaround: 


¢ Section 30.12.1, “Users Cannot Register a Client Application,” on page 1263 
¢ Section 30.12.2, “Token Exchanges Show Redirect URI Invalid Error,” on page 1263 


¢ Section 30.12.3, “Users Cannot Register or Modify a Client Application with Specific Options,” on 
page 1263 


¢ Section 30.12.4, “A Specific Claim Does Not Come to the UserInfo Endpoint during Claims 
Request,” on page 1264 


¢ Section 30.12.5, “Access Gateway OAuth Fails,” on page 1264 
¢ Section 30.12.6, “After Allowing Consent, 500 Internal Server Error Occurs,” on page 1264 


¢ Section 30.12.7, “No Error Message When a Token Request Contains Repetitive Parameters,” 
on page 1264 


¢ Section 30.12.8, “Oauth Token Encryption/Signing Key Is Compromised or Corrupted,” on 
page 1264 


¢ Section 30.12.9, “Tracing OAuth Requests,” on page 1265 


¢ Section 30.12.10, “OAuth Client Registration Fails If a Role Policy Contains a Condition Other 
than LDAP Attribute, LDAP Group, or LDAP OU,” on page 1265 


¢ Section 30.12.11, “The Identity Injection Policy Does Not Inject Passwords,” on page 1266 
¢ Section 30.12.12, “OAuth Apps Fail After Upgrading Access Manager,” on page 1266 


30.12.1 Users Cannot Register a Client Application 


In Administration Console, verify whether the user has role NAM_OAUTH2_DEVELOPER or 
NAM_OAUTH2_ADMIN configured in Identity Server Role policy configuration. 


Verify the REST communication between browser and Identity Server by using Chrome developer 
console. 


30.12.2 Token Exchanges Show Redirect URI Invalid Error 


Go to Administration Console > Devices > Identity Servers > Edit > OAuth & OpenID Connect > 
Client Applications. Open the client application and verify whether the specified URI is configured for 
the client application. 


30.12.3 Users Cannot Register or Modify a Client Application with 
Specific Options 


Verify the options enabled for the client application. An administrator must enable same options in the 
Global Settings page. 
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30.12.6 


30.12.7 


30.12.8 


A Specific Claim Does Not Come to the UserlInfo Endpoint 
during Claims Request 


Verify the following points: 
+ Whether the user has a value for that attribute. If the value is empty, Userlnfo does not return 
any value in JSON. 


+ The Identity Sever has provided the requested scope. You can check this with the TokenInfo 
endpoint by providing an Access token. 


¢ The scope contains the attribute mapping for the missing attribute. 
You can access only LDAP attributes as claims at this time. 


Access Gateway OAuth Fails 


Perform the following actions: 


+ Verify whether Activate OAuth is selected for the Protected Resource. 


¢ Verify authorization policies are configured. Also, verify if the token contains required scopes by 
using the TokenInfo endpoint. 


¢ Verify Identity Injection policies. Enable Application debug logs in Identity Server and ESP and 
check for policy results. 


After Allowing Consent, 500 Internal Server Error Occurs 


Verify whether the attribute you have configured in the Global Setting page is available and stored in 
the user store. Ensure that the correct attribute to store authorization grant is available in the user 
store and it is writable to the user store. 


No Error Message When a Token Request Contains 
Repetitive Parameters 
Ensure that you do not send the same parameter multiple times in a single request. The base 


framework reads only last or first available parameters if multiple query parameters have the same 
name. 


Oauth Token Encryption/Signing Key Is Compromised or 
Corrupted 


Regenerate the token encryption/signing key by using the following steps: 


1 Delete the nidsOAuthKeysXML attribute from the e-Directory at the following location: 


o=novell, ou=accessManagerContainer, cn=nids, cn=cluster, cn=IDP_Cluster, 
cn=0Auth_Container 


2 Go to Administration Console and click Devices > Identity Server > Edit. 
3 Update Identity Server cluster. 
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Tracing OAuth Requests 


You can trace each OAuth request and response by setting the following property in tomcat . conf. 
Add the following line in /opt/novell/nam/idp/conf/tomcat . conf: 

JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.nidp.oauth. jersey.trace=ALL" 

You can specify the following parameters: 


+ OFF: tracing support is disabled (default value) 


+ ON_DEMAND: tracing support in a stand-by mode. It is enabled selectively per request through 
a special X-Jersey-Tracing-Accept HTTP request header. The Jersey tracing facility does not 
use the value of the X-Jersey-Tracing-Accept header and as such, it can be any arbitrary string. 


¢ ALL: tracing support is enabled for all requests 
You can customize the level of detail of the information (tracing threshold) provided by Jersey tracing 
facility. You can set the tracing threshold at a request level through X-Jersey-Tracing-Threshold HTTP 
request header. The request level configuration overrides any application level setting. Supported 
levels include SUMMARY, TRACE, and VERBOSE. 

¢ SUMMARY: basic summary information about the main request processing stages 


¢ TRACE: detailed information about activities in all main request processing stages (default 
threshold value) 


¢ VERBOSE: extended information similar to the TRACE level, however it includes details about 
entity providers (MBR/MBW) that were skipped during the provider selection phase for any 
reason (such as lower priority or pattern matching). Additionally, in this mode all received request 
headers are echoed as part of the tracing information. 


For more information, see Monitoring and Diagnostics. 


OAuth Client Registration Fails If a Role Policy Contains a 
Condition Other than LDAP Attribute, LDAP Group, or LDAP 
OU 


For registering OAuth client applications by using Identity Server, you must have a role called 
NAM_OAUTH2_DEVELOPER assigned. 


The following are the recommended conditions in an Identity Server Role policy that assigns the 
NAM_OAUTH2_DEVELOPER role: 


+ LDAP Attribute 
+ LDAP Group 
+ LDAP OU conditions 


The client registration will not work if this role policy contains any of the following conditions: 


+ Authenticating IDP 

+ Authentication Contract 
+ Authentication Method 
+ Authentication Type 

¢ Credential Profile 
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¢ Liberty User profile 
+ Roles from Identity Provider 
+ User Store 


The Identity Injection Policy Does Not Inject Passwords 


Verify logs by enabling the debug level. Verify whether, in Identity Server, the userinfo request is 
coming with sp-id. Logs should include the fetching password for user term. If any issue occurs, 
the log includes the error message. 


OAuth Apps Fail After Upgrading Access Manager 


The OAuth apps fail after you upgrade Access Manager. This is caused due to the expired 
authorization code. 


To workaround this issue, you need to upgrade both Access Gateway and Identity Server to Access 
Manager at the same time. For more information, see TID. 


Troubleshooting User Attribute Retrieval and 
Transformation 


This section discusses how to troubleshoot any issue occurred in User Attribute Retrieval and 
Transformation feature. 


¢ Section 30.13.1, “No Value Is Fetched from Attribute Source in Identity Server,” on page 1266 
¢ Section 30.13.2, “Error Message While Testing a Database Connection,” on page 1266 
¢ Section 30.13.3, “Regex Replace Error Message,” on page 1267 


No Value Is Fetched from Attribute Source in Identity Server 


In Identity Server, no Attribute Source value is fetched from the data source. However, the test 
functionality fetches the data and displays the correct result in Administration Console. 


To troubleshoot this issue, check the error logs for any Data Source connection issues. 


¢ Linux: /opt/novell/nam/logs/idp/tomcat/catalina.out 
+ Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout. log 


If the Data Source is a database, ensure that the driver jars are available in both Identity Server and 
Administration Console. If the Data Source is a secure LDAP connection, ensure that SSL certificate 
of the LDAP directory is imported in Identity Server's trust store. Update all Identity Servers. 


Error Message While Testing a Database Connection 


Error 1: 


While testing a database connection, if the error message displays: "Driver 
com.microsoft.sqlserver.jdbc.SQLServerDriver claims to not accept JDBC URL..... È 
then the issue can be due to the format of the specified URL. 
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To troubleshoot this issue, specify a correct format of the JDBC URL. You can refer to the example 
specified in the Edit Data Source interface. 


Error 2: 


While testing a database connection, if the error message displays: “driverClassName specified 
class 'com.microsoft.sqlserver.jdbc.SQLServerDriver' could not be loaded”, or 
“driverClassName specified class 'oracle.jdbc.driver.OracleDrive' could not be 
loaded’, then the issue is with the respective drivers. 


To troubleshoot this issue, add the corresponding database drivers in Administration Console and 
Identity Server respectively. Restart Administration Console and Identity Server. 


Error 3: 


While testing a data source connection, if the error message displays: "Exception during pool 
initialization", then the issue can be with the incorrect SID specified in the database URL or due 
to incorrect port or hostname. 


To troubleshoot this issue, check the error logs for any data source connection issues: 


+ Linux: /opt/novell/nam/logs/adminconsole/tomcat/catalina.out 


+ Windows: \Program Files (x86)\Novell\Tomcat\logs\stdout. log 


Regex Replace Error Message 


While performing a regex replace function, if you specify /a, then, the following error message 
displays: 


¢ On Firefox browser: Incorrect syntax : invalid regular expression flag a 


+ On Chrome browser: Incorrect syntax : Invalid flags supplied to RegExp 
constructor 'a' 


To troubleshoot this issue, ensure that you specify a correct regular expression. For example: i (case 
insensitive), g (global search) are valid flags. A regular expression has the following format: 


/pattern/modifiers. Example: var patt = /abc/i. Where, /abc/i is a regular expression and abc 
is a pattern (used in the search). i is a modifier (modifies the search to be case-insensitive). 


Troubleshooting Impersonation 


This section discusses how to troubleshoot any issue occurred during Impersonation. 


Internet Explorer Caching Error 


If you perform Impersonation by using Internet Explorer, there is a caching error. You can view only 
the outdated cached information instead of the latest saved configuration. 


To troubleshoot this issue, you need to make the following change in the cache settings of Internet 
Explorer: 

1 In Internet Explorer, click Tools > Internet Options. 

2 Go to General tab > Browsing history > Settings. 


3 Under the Check for newer versions of stored pages option, select Every time | visit the 
webpage. 
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Troubleshooting Branding 


This section discusses how to troubleshoot any issue that occur when you change the Branding for 
the User Portal page. 


Changes to Branding do not Appear in Administration 
Console 


Issue: If you have more than one Administration Console, after you make changes to Branding for 
the User Portal page and save the changes, the changes do not appear in Administration Console. 


Solution: Access Manager synchronizes the changes between Administration Consoles and this can 
take some time. There is a built-in delay so that the changes have time to synchronize between 
Administration Consoles. If you need a further delay than the built-in delay, you can increase the 
delay with a Java parameter. The Java parameter is defined in a configuration file on Linux and as a 
registry key on Windows servers. 


This problem occurs when you make changes to MobileAccess as well. If you make the change for 
Branding, you do not need to make additional changes to fix Branding. The solution is the same for 
both features. 


To add the Java parameter: 
1 (Conditional) If you have a Linux server, you must edit the tomcat7.conf file located here /opt/ 
novell/nam/adminconsole/conf/tomcat7.conf. 
1a Open the tomcat7.conf file in a text editor. 
1b Add the following parameter with a delay value that is appropriate for your environment: 


JAVA_OPTS="${JAVA_OPTS} -DAMSrvDoorBellDelay=10000" 


The value is in milliseconds. This example increases the delay to 10 seconds. 
1c Save and close the tomcat7.conf file. 
1d Restart Tomcat to have the parameter take effect. 


/etc/init.d/novell-ac restart 


2 (Conditional) If you have a Windows server, you must add a registry key. 
2a Launch the Registry Editor as an administrator, by clicking Start > Run, then enter regedit. 


2b Inthe left pane of the Registry Editor, navigate to My Computer > HKEY_ LOCAL MACHINE 
>SOFTWARE > Wow6432Node > Apache Software Foundation > Procurn2.0 > Tomcat7 > 
Parameters > Java. 


2c Double-click Options in the right pane of the Registry Editor. 
2d Add the following key with the delay value that is appropriate for your environment: 


-DAMSrvDoorBellDelay=10000" 


The value is in milliseconds. This example increases the delay to 10 seconds. 
2e Close the Registry Editor. 
2f Restart Tomcat by using the following commands: 


net stop Tomcat7 
net start Tomcat7 
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30.16 


30.16.1 


30.16.1.1 


Using Log Files for Troubleshooting 


The following sections provide information about how to use log files for troubleshooting problems: 


¢ Section 30.16.1, “Sample Authentication Traces,” on page 1269 
e Section 30.16.2, “Understanding Policy Evaluation Traces,” on page 1273 
¢ Section 30.16.3, “Adding Hashed Cookies into Browsers,” on page 1291 


Sample Authentication Traces 


An authentication trace is logged to the catalina. out file of Identity Server that authenticates the 
user. If Access Gateway initiates the authentication because of a user request to a protected 
resource, the Embedded Service Provider log file of Access Gateway also contains entries for the 
authentication sequence. Identity Server logging must be enabled to produce authentication traces 
(see Section 21.3.1, “Configuring Logging for Identity Server,” on page 1038). 


This section describes the following types of authentication traces: 


¢ Section 30.16.1.1, “Direct Authentication Request to Identity Server,” on page 1269 
¢ Section 30.16.1.2, “Protected Resource Authentication Trace,” on page 1271 


Direct Authentication Request to Identity Server 


The following trace is an example of a user logging directly into Identity Server to access the end user 
portal. The log entries are numbered, so that they can be described. 


1. <amLogEntry> 2009-06-14T17:14:30Z INFO NIDS Application: AM#500105015: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD7F2EEDEB3D17F99EC3F39D1: Processing 
login request with TARGET = http://10.10.15.19:8080/nidp/app, saved TARGET = . </ 
amLogEntry> 


2. <amLogEntry> 2009-06-14T17:14:30Z INFO NIDS Application: AM#500105009: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD7F2EEDEB3D17F99EC3F39D1: Executing 
contract Name/Password - Form. </amLogEntry> 


3. <amLogEntry> 2009-06-14T17:14:30Z INFO NIDS Application: AM#500105010: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD/7F2EEDEB3D17F99EC3F39D1: Contract 
Name/Password - Form requires additional interaction. </amLogEntry> 


4. <amLogEntry> 2009-06-14T17:14:39Z INFO NIDS Application: AM#500105015: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD7F2EEDEB3D17F99EC3F39D1: Processing 
login request with TARGET = http://10.10.15.19:8080/nidp/app, saved TARGET = http:/ 
/10.10.15.19:8080/nidp/app. </amLogEntry> 


5. <amLogEntry> 2009-06-14T17:14:39Z INFO NIDS Application: AM#500105009: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD7F2EEDEB3D17F99EC3F39D1: Executing 
contract Name/Password - Form. </amLogEntry> 


6. <amLogEntry> 2009-06-14T17:14:39Z INFO NIDS Application: AM#500105014: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD/7F2EEDEB3D17F99EC3F39D1: Attempting 
to authenticate user cn=bcf,o=novell with provided credentials. </amLogEntry> 


7. <amLogEntry> 2009-06-14T17:14:39Z WARNING NIDS Application: Event Id: 3014666, 
Target: cn=bcf,o=novell, Sub-Target: F35A3C7AD7F2EEDEB3D17F99EC3F39D1, Note 1: 
Local, Note 2: This Identity Provider, Note 3: name/password/uri, Numeric 1: © </ 
amLogEntry> 
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8. <amLogEntry> 2009-06-14T17:14:39Z WARNING NIDS Application: Event Id: 3015456, 
Note 1: F35A3C7AD7F2EEDEB3D17F99EC3F39D1, Note 2: Manager, Note 3: 
Document=(ou=xpem1PEP, ou=mastercdn, ou=Content 

PublisherContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManag 
erContainer, o=novell: romaContentCollectionXMLDoc),Policy=(Manager ),Rule=(1::RuleID 
_1181251958207), Action=(AddRole: :ActionID_1181252224665), Numeric 1: 0 </ 
amLogEntry> 


9. <amLogEntry> 2009-06-14T17:14:39Z WARNING NIDS Application: Event Id: 3015456, 
Note 1: F35A3C7AD7F2EEDEB3D17F99EC3F39D1, Note 2: authenticated, Note 3: system- 
generated-action, Numeric 1: © </amLogEntry> 


10. <amLogEntry> 2009-06-14T17:14:39Z INFO NIDS Application: AM#500199050: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD/7F2EEDEB3D17F99EC3F39D1: IDP 
RolesPep.evaluate(), policy trace: 
~~RL~1~~~~Rule Count: 1~~Success(67) 
~~RU~RuleID_1181251958207~Manager~DNF~~1:1~~Success (67) 
~~CS~1~~ANDs~~1~~True(69) 
~~C0~1~LdapGroup(6645) :no-param:hidden-value:~ldap-group-is-member - 
of~SelectedLdapGroup (66455) :hidden-param: hidden- value: ~~~True(69) 
~~PA~ActionID_1181252224665~~AddRole~Manager~~~Success(0) 
~~PC~ActionID_1181252224665~~Document=(ou=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=a 
ccessManagerContainer, o=novell: romaContentCollectionXMLDoc),Policy=(Manager ), Rule= 
(1: :RuleID_1181251958207), Action=(AddRole: :ActionID_1181252224665 )~AdditionalRole( 
6601) : unknown( ) : Manager :~~~Success(0) 
</amLogEntry> 


11. <amLogEntry> 2009-06-14T17:14:39Z INFO NIDS Application: AM#500105013: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD/7F2EEDEB3D17F99EC3F39D1: 
Authenticated user cn=bcf,o=novell in User Store Local Directory with roles 
Manager, authenticated. </amLogEntry> 


12. <amLogEntry> 2009-06-14T17:14:39Z INFO NIDS Application: AM#500105017: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#F35A3C7AD7F2EEDEB3D17F99EC3F39D1: nLogin 
succeeded, redirecting to http://10.10.15.19:8080/nidp/app. </amLogEntry> 


Table 30-3 Log Entry Descriptions for an Authentication Trace from an Identity Server 


Entry Description 


1 Indicates that a login request is in process. This is the first entry for a login request. The requester, 
even though login has not been successful, is assigned an authentication ID. You can use this ID to 
find the log entries related to this user. The entry also specifies the URL of the requested resource, in 
this case the /nidp/app resource called the End User Portal. The saved TARGET message does not 
contain a value, so this step will be repeated. 


2 Specifies the contract that is being used to perform the login. 
3 Indicates that the contract requires interaction with the user. 
4 Indicates that the a login request is in process. The saved TARGET message contains a value, so 


the required information has been gathered to start the authentication request. The AM# correlation 
tag is AM#500105015, which is the same value as the first log entry. 


5 Indicates that an exchange is occurring between the client and Identity Server to obtain the required 
credentials. Each contract requires a different exchange. The AM# correlation tag is AM#500105009, 
which is the same value as the second log entry. 
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Entry Description 


6 Provides the DN of the user attempting to log in and indicates that the user’s credentials are being 
sent to the LDAP server for verification. 


7 Provides information about an auditing event. If you have not enabled auditing or you have not 
selected the login events, this entry does not appear in your log file. This event contains information 
about who is logging in and the contract that is being used. 


8 Provides information about an auditing event. If you have not enabled auditing or you have not 
selected the login events, this entry does not appear in your log file. This event contains information 
about the Manager policy that is evaluated during login. 


9 Provides information about an auditing event. If you have not enabled auditing or you have not 
selected the login events, this entry does not appear in your log file. 


10 Contains the entry for processing a Role policy. When a user logs in, all Role policies are evaluated 
and the user is assigned any roles that the user has the qualifications for. For more information, see 
Section 30.16.2, “Understanding Policy Evaluation Traces,” on page 1273. 


11 Contains a summary of who logged in from which user store and the names of the Role policies that 
successfully assigned roles to the user. 


12 Contains the final results of the login, with the URL that the request is redirected to. 


30.16.1.2 Protected Resource Authentication Trace 


When a protected resource is configured to require authentication, both Identity Server and the 
Embedded Service Provider of Access Gateway generate log entries for the process. The following 
sections explain how to correlate the entries from the logs. 

¢ “Entries from an Identity Server Log” on page 1272 

¢ “Entries from an Access Gateway Log” on page 1273 


¢ “Correlating the Log Entries between Identity Server and Access Gateway” on page 1273 
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Entries from an Identity Server Log 


<amLogEntry> 2009-07-31T17:36:39Z INFO NIDS Application: AM#500105016: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#837 78AEQ9DCA5A35B57842D754A60D67: Processing 
login resulting from Service Provider authentication request. </amLogEntry> 


<amLogEntry> 2009-07-31T17:36:39Z INFO NIDS Application: AM#500105009: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#83778AE09DCA5A35B57842D754A60D67: Executing 
contract Name/Password - Form. </amLogEntry> 


<amLogEntry> 2009-07-31T17:36:39Z INFO NIDS Application: AM#500105010: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#837 78AEQ9DCA5A35B57842D754A60D67: Contract 
Name/Password - Form requires additional interaction. </amLogEntry> 


<amLogEntry> 2009-07-31T17:36:49Z INFO NIDS Application: AM#500105016: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#837 78AEQ9DCA5A35B57842D754A60D67: Processing 
login resulting from Service Provider authentication request. </amLogEntry> 


<amLogEntry> 2009-07-31T17:36:49Z INFO NIDS Application: AM#500105009: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#83778AE09DCA5A35B57842D754A60D67: Executing 
contract Name/Password - Form. </amLogEntry> 


<amLogEntry> 2009-07-31T17:36:49Z INFO NIDS Application: AM#500105014: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#837 78AEQ9DCA5A35B57842D754A60D67: Attempting 
to authenticate user cn=admin, o=novell with provided credentials. </amLogEntry> 


<amLogEntry> 2009-07-31T17:36:49Z INFO NIDS Application: AM#500105012: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#83778AEQ09DCA5A35B57842D754A60D67: 
Authenticated user cn=admin, o=novell in User Store Internal with no roles. </ 
amLogEntry> 


<amLogEntry> 2009-07-31T17:36:49Z INFO NIDS Application: AM#500105018: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#837 78AEQ9DCA5A35B57842D754A60D67: Responding 
to AuthnRequest with artifact AAMoz+rm2jQjDSHjea8U9zm3Td/U2ax0YZCo/ 
QBNool8WkZiTCt7N7Jx </amLogEntry> 


<amLogEntry> 2009-07-31T17:36:49Z INFO NIDS Application: AM#500105019: 
AMDEVICEID#AA257DA77ED48DB0: AMAUTHID#C2D8D52704918AF2D5D62F6EDC2FFAC6: Sending 
AuthnResponse in response to artifact AAMoz+rm2j]Qj]DSH]ea8U9zZm3Td/U2ax0YZCo/ 
QBNool8WkZiTCt7N7Jx </amLogEntry> 
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Entries from an Access Gateway Log 


<amLogEntry> 2009-07-31T17:35:05Z INFO NIDS Application: AM#500105005: 
AMDEVICEID#esp -2FA73CE1A376FD91: AMAUTHID#C6D119FD93EEBBEBEC50BEB27B9E2832: 
Processing proxy request for login using contract name/password/uri and return url 
http://jwilson.provo.novell.com/ </amLogEntry> 


<amLogEntry> 2009-07-31T17:35:05Z INFO NIDS Application: AM#500105015: 
AMDEVICEID#esp -2FA73CE1A376FD91: AMAUTHID#C6D119FD93EEBBEBEC50BEB27B9E2832: 
Processing login request with TARGET = http://jwilson.provo.novell.com/, saved 
TARGET = . </amLogEntry> 


<amLogEntry> 2009-07-31T17:35:05Z INFO NIDS Application: AM#500105009: 
AMDEVICEID#esp -2FA73CE1A376FD91: AMAUTHID#C6D119FD93EEBBEBEC50BEB27B9E2832: 
Executing contract IDP Select. </amLogEntry> 


<amLogEntry> 2009-07-31T17:35:05Z INFO NIDS Application: AM#500105010: 
AMDEVICEID#esp -2FA73CE1A3/76FD91: AMAUTHID#C6D119FD93EEBBEBEC50BEB27B9E2832: 
Contract IDP Select requires additional interaction. </amLogEntry> 


<amLogEntry> 2009-07-31T17:35:15Z INFO NIDS Application: AM#500105020: 
AMDEVICEID#esp -2FA73CE1A376FD91: AMAUTHID#C6D119FD93EEBBEBEC50BEB27B9E2832: 
Received and processing artifact from IDP - AAMoz+rm2jQjDSHjea8U9zm3Td/U2ax0YZCo/ 
QBNool8WkZiTCt7N7Jx </amLogEntry> 


<amLogEntry> 2009-07-31T17:35:15Z INFO NIDS Application: AM#500105021: 
AMDEVICEID#esp -2FA73CE1A376FD91: AMAUTHID#C6D119FD93EEBBEBEC50BEB27B9E2832: 
Sending artifact AAMoz+rm2jQjDSHjea8U9zm3Td/U2ax0YZCo/qBNool8WkZiTCt7N7Jx to URL 
http://jwilson1.provo.novell.com:8080/nidp/idff/soap at IDP </amLogEntry> 


Correlating the Log Entries between Identity Server and Access Gateway 


You can see that these two trace sequences are for the same authentication request because the 
artifact (AAMoz+rm2jQjDSHjea8U9zZm3Td/U2ax0YZCo/qBNool8WkZiTCt7N7Jx) that is exchanged is 
the same. You can use the AMAUTHID in each file to search for other requests that this user has made. 


To associate a distinguished name with the AMAUTHID, use the catalina. out file of Identity Server. 
Event AM#500105014 contains the DN of the user. 


30.16.2 Understanding Policy Evaluation Traces 


¢ Section 30.16.2.1, “Format,” on page 1273 
Section 30.16.2.2, “Policy Result Values,” on page 1280 
Section 30.16.2.3, “Role Assignment Traces,” on page 1281 


+ 


+ 


+ 


Section 30.16.2.4, “Identity Injection Traces,” on page 1283 


+ 


Section 30.16.2.5, “Authorization Traces,” on page 1284 
Section 30.16.2.6, “Form Fill Traces,” on page 1286 


+ 


30.16.2.1 Format 


A policy log entry starts with the standard log entry elements: <amLogEntry> followed by the 
correlation tags. 


(For information about correlation tags, see “Understanding the Correlation Tags in the Log Files” on 
page 1036.) 
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The following log entry is a trace of an evaluation of a Role policy: 


<amLogEntry> 2009-06-07T21:40:25Z INFO NIDS Application: AM#500199050: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#503EFFA4BC21ACA307796EC7D96E5532: IDP 
RolesPep.evaluate(), policy trace: 
~~RL~OQ~~~~Rule Count: 1~~Success(67) 
~~RU~RuleID_1181251958207~Manager~DNF~~1:1~~Success (67) 
~~CS~1~~ANDsS~~1~~True(69) 
~~CO~1~LdapGroup(6645) :no-param:hidden-value:~ldap-group-is-member - 
of~SelectedLdapGroup(66455) :hidden-param:hidden-value:~~~True(69) 
~~PA~ActionID_1181252224665~~AddRole~Manager~~~Success(0) 
~~PC~ActionID_1181252224665~~Document=(ou=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=a 
ccessManagerContainer, o=novell: romaContentCollectionXMLDoc),Policy=(Manager ),Rule= 
(1: :RuleID_1181251958207), Action=(AddRole: :ActionID_1181252224665 )~AdditionalRole( 
6601) : unknown( ) :Manager :~~~Success(0) 
</amLogEntry> 


The Role policy evaluated in this entry has the following definition: 
Figure 30-9 Manager Policy Definition 


Edit Policy: Manager - Rule 1 
Type: Identity Server: Roles 


Description: Assigns the role of Manager to members of the LDAP Manager group | 


Priority: 1 & 


Conditions Condition structure: | AND Conditions, OR groups Y | 


E Condition Group 1 


LDAP Group: [Current] 
Comparison: LDAP Group: Is Member of w 
Value: LDAP Group w cn=/\anagers,o=novell w 
Result on Condition Error: False w 


Append New Group | 


Actions 


Activate Role 
Do Activate Role 


A Manager 


Changes made on this panel must be applied from the Policies Panel. 


OK | Cancel 


The following sections use this policy and its trace to explain the information contained within each 
line of a policy trace. The policy trace part of the entry starts with a policy trace:, which is followed 
by one or more of the following types: 


¢ RL- Rule List Evaluation Result (page 1275) 

¢ RU - “Rule Evaluation Result” on page 1275 

¢ CS - Condition Set Evaluation Result (page 1276) 
¢ CO - Condition Evaluation Result (page 1277) 
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¢ PA - Policy Action Initiation (page 1278) 
+ PC - Policy Action Completion (page 1279) 


Elements within a type are separated from each other with the tilde (~) character. If an element does 
not have a value, no value is inserted, which results in two or more tildes between values. Two tildes 
means one element didn’t have a value, three tildes means that two elements didn’t have values, and 


so forth. 


Rule List Evaluation Result 

An RL trace has the following fields: 
~<RuleListID>~~~~<RuleCount>~~<Result> 
A RL trace looks similar to the following: 
~~RL~1~~~~Rule Count: 1~~Success(67) 


Table 30-4 describes the fields found in an RL trace. 


Table 30-4 Fields in a Rule List Trace 


Element Description 
<RuleListID> The identifier assigned to the rule list. 

In the sample RL trace, this is 1. 
<RuleCount> The number of rules defined for the policy. 


In the sample RL trace, this is Rule Count: 1, indicating that there is one 
rule in the policy. 


<Result> A string followed by a number that specifies the result of the evaluation. See 
“Policy Result Values” on page 1280. 


In the sample RL trace, this is Success(67), indicating success. 


Rule Evaluation Result 
An RU trace has the following fields: 


~<RuleID>~<ParentPolicyName>~<ConditionSet JoinType>~~<ConditionSetCount: 
ActionCount>~~<Result> 


An RU trace looks similar to the following: 
~~RU~RuleID_1181251958207~Manager~DNF~~1:1~~Success (67) 


Table 30-5 describes the fields of a Rule Evaluation Result trace. 
Table 30-5 Fields in a Rule Evaluation Result Trace 


Element Description 


<RuleID> The identifier assigned to the rule. 


In this sample RU trace, this element is set to 
RuleID_1181251958207. 
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Element 


<ParentPolicyName> 


<ConditionSet JoinType> 


Description 


The name of the parent policy to which the rule is assigned. 
In this sample RU trace, this element is set to Manager. 


The type of joining that occurs between conditions and 
condition sets. It is set to one of the following: 


+ CNF: Indicates that sets are ANDed and conditions 
within a condition group are ORed. 


+ DNF: Indicates that sets are ORed and conditions within 
a condition group are ANDed. 


In the sample RU trace, this element is set to DNF. 


<ConditionSetCount :ActionCount> The number of condition sets and actions defined for this rule. 


<Result> 


In the sample RU trace, this is 1:1, for one condition set and 
one action. 


A string followed by a number that specifies the result of the 
evaluation. See “Policy Result Values” on page 1280. 


In the sample RU trace, this is Success(67), indicating that 
the rule was successfully evaluated. 


Condition Set Evaluation Result 


ACS trace has the following fields 


~<ConditionSet ID>~<JoinType>~<NOT>~<ConditionCount>~~<Result> 


ACS trace looks similar to the following: 


~~CS~1~~ANDs~~1~~True(69) 


Table 30-6 describes the fields in a Condition Set trace. 


Table 30-6 Fields in a Condition Set Trace 


Element 


<ConditionSetID> 


<JoinType> 


<NOT> 
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Description 


The identifier assigned to the condition set. Rules can have multiple condition 
sets. 


In this sample CS trace, this is 1, for the first and only condition set defined for 
the rule. 


Specifies how the condition results are combined, if there are multiple condition 
sets. Possible values include ANDs and ORs. 


In this sample CS trace, this is ANDs. 


The string NOT if the result was negated prior to reporting; otherwise the field 
has no value. This is the If Not option when creating a condition group. 


In the sample CS trace, the condition group was not negated, therefore the 
field is not present. 


Element 


<ConditionCount> 


<Result> 


Description 
The number of conditions defined in the condition group. 
In the sample CS trace, this element has the value of 1. 


A string followed by a number that specifies the result of the evaluation. See 
“Policy Result Values” on page 1280. 


In the sample CS trace, this is True (69), indicating that the condition evaluated 
to True. 


Condition Evaluation Result 


ACO trace has the following fields: 


~<ConditionID>~<LHSOperand>~<Operator>~<RHSOperand>~<NOT>~<Result>[~<ResultOnError 


>] 


A CO trace looks similar to the following: 


~~C0O~1~LdapGroup (6645) :no-param: hidden-value:~ldap-group-is-member - 
of~SelectedLdapGroup (66455) :hidden-param: hidden- value: ~~~True(69) 


Table 30-7 describes the fields in a Condition trace. 


Table 30-7 Fields in a Condition Trace 


Element 


<ConditionID> 


<LHSOperand> 


Description 


The identifier assigned to the conditions in the condition group. The first 
condition is assigned 1. 


In the sample CO trace, this is 1. 


The enumerative value and parameter list of the left operand. It is the first 
value specified for the comparison and has the following format: 


<Condition Name(Data ID)>: <Parameter> : <Value> 


The Condition Name is the string assigned to the condition type specified in the 
policy. The Data ID is a numerical value assigned to the condition type. 


<Parameter> contains one of the following strings: 


+ no-param when no parameters are specified for the operand, followed by 
a colon, followed by one of the following: the value, no- value, or 
hidden-value when the value contains sensitive information. 


+ hidden-param followed by a colon, and then hidden-value. This string 
is used when both the parameter and its value contain sensitive 
information. 


In the sample CO trace, this is LdapGroup(6645) :no-param:hidden- 
value. LdapGroup is the string for the LDAP Group condition. The policy 
specified [Current], so no parameters were specified. The groups that the user 
belongs to are considered sensitive data, so the log file displays hidden- 
value for the names of the groups. 
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Element 


<Operator> 


<RHSOperand> 


<NOT> 


<Result> 


<ResultOnError> 


Policy Action Initiation 


Description 
The display name of the comparison operator. 


In the sample CO trace, this is ldap-group-is-member - of. In the policy, this 
is displayed as LDAP Group: Is Member of. 


The enumerative value and parameter list of the right operand. It is the second 
value specified for the comparison and has the same format as the 
<LHSOperand>. 


In the sample CO trace, this is SelectedLdapGroup (66455) :hidden- 
param: hidden-value. The actual policy specifies LDAP Group as the 
parameter, and the value is the DN of the group. 


The string NOT if the result was negated prior to reporting; otherwise the field 
has no value. This is the If Not option when creating a condition. 


In the sample CO trace, this condition result was not negated, therefore the 
field is represented by a tilde. 


A string followed by a number that specifies the result of the comparison. See 
“Policy Result Values” on page 1280. 


In the sample CO trace, this is True (69), indicating that the condition evaluated 
to True—the user is a member of the specified LDAP group. 


A string describing the error that occurred. This is an optional field that only 
appears when the condition evaluation results in an error. 


The sample CO trace did not result in an error, so it has no string. 


A PA trace has the following fields: 


~<ActionID>~<TraceString1>~<TraceString2>~<TraceString3>~<Result> 


A PA trace looks similar to the following: 


~~PA~ActionID_1181252224665~~AddRole~Manager~~~Success(0) 
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Table 30-8 describes the fields in a Policy Action trace. 


Table 30-8 Fields in a Policy Action Trace 


Element Description 


<ActionID> The identifier assigned to the action. In the sample PA trace, this is 
ActionID_1181252224665. 


<TraceStringi> The message specified with the action. 
In the sample PA trace, this is AddRole. 
<TraceString2> The second part of the specified message. 
In the sample PA trace, this is Manager. 
<TraceString3> The third part of the specified message. 
In the sample PA trace, this field has no value and is not present. 


<Result> A string followed by a number that specifies the result of the assigning the action. See 
“Policy Result Values” on page 1280. 


In the sample PA trace, this is Success(0), which indicates that the action of assigning 
the Manager role to the user was successful. 
Policy Action Completion 
A PC trace has the following fields 
~<ActionID>~<ActionName>~<ActionParmeters>~~~<Result>[~<ActionError>] 
A PC trace looks similar to the following: 


~~PC~ActionID_1181252224665~~Document=(ou=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=a 
ccessManagerContainer, o=novell: romaContentCollectionXMLDoc),Policy=(Manager ),Rule= 
(1: :RuleID_1181251958207), Action=(AddRole: :ActionID_1181252224665 )~AdditionalRole( 
6601) : unknown( ) :Manager :~~~Success(0) 


Table 30-9 describes the fields in a Policy Action Completion trace. 
Table 30-9 Fields in a Policy Action Completion Trace 


Element Description 


<ActionID> The ID assigned to the action. 


In the sample PC trace, this is ActionID_1181252224665. 
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Element 


Description 


The fully distinguished name of the action. 


In the sample PC trace, the action has the following parts in its name: 


+ Document=(ou=xpemIPEP,ou=mastercdn, 
ou=ContentPublisherContainer,ou=Partition,ou=PartitionsContainer,ou=V 
CDN_Root,ou=accessManagerContainer,o=novell:romaContentCollectio 


+ Rule=(1::RulelD_1181251958207) 
+ Action=(AddRole::ActionID_1181252224665) 


A list of the action parameters passed to the action handler. 


In this sample PC trace, the Role policy has an action and a parameter. The 
value of this element is AdditionalRole( 6601) :unknown(): Manager: 


A string followed by a number that specifies the result. See “Policy Result 


In the sample PC trace, this is Success(@)and indicates success. 


<ActionName> 
nXMLDoc) 
+ Policy=(Manager) 
<ActionParmeters> 
<Result> 
Values” on page 1280. 
<ActionError> 


30.16.2.2 


A string describing the error that occurred when invoking the action. This is an 


optional field that only appears when the Result field contains an error code. 


The sample PC trace did not result in an error, so it has no string. 


Policy Result Values 


The last field in a trace string is the <result> field. Table 30-10 lists the possible values: 


Table 30-10 Result Values from Policy Traces 


Value 


0 
1 


67 
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Name 

Success 

Error: No memory 
Error: Bad data 


Error: Configuration initialization 


Error: General failure 
Pending 

Permit 

Deny 

Obligation 


No action 


Description 


The policy evaluation was successful. 
The system is out of memory. 
The data sent for evaluation is invalid. 


An error was detected during the policy configuration 
processing. 


An error was detected during policy processing. 
The policy processing is in progress. 

The rule produced a Permit action. 

The rule produced a Deny action. 


The rule triggered an obligation, indicating that additional 
processing is required. Identity Injection policies trigger 
obligations. 


The rule did not initiate any action. 


30.16.2.3 


Value Name Description 


68 Condition false The condition evaluated to False. 

69 Condition true The condition evaluated to True. 

70 Condition unknown Condition input was not available, so the results are 
unknown. 

71 Cancel The current operation has been canceled. 

72 Error: Interface unavailable The current operation is unavailable. 

73 Error: Data unavailable The data required for evaluation was unavailable. 

74 Error: Illegal state Processing error; report it to Novell® Support. 


Role Assignment Traces 


The following sections walk you through a few sample role traces. When you understand these 
traces, you should be able to understand any role trace. 


+ “When the User Is Assigned Roles” on page 1281 
+ “When the Role Policy Is Not Enabled” on page 1282 
e “When an Authorization Policy Uses a Role” on page 1282 


When the User Is Assigned Roles 


Roles are assigned at authentication, so this type of trace is found in the catalina. out file (Linux) or 
the stdout .1og file (Windows) of Identity Server. This is a trace of a user who does not match the 
requirements to be assigned the Manager Role (for a definition of this Role policy, see Figure 30-9 on 
page 1274). 


<amLogEntry> 2009-06-11T15:38:38Z INFO NIDS Application: AM#500199050: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#OCE611AAE4D0301F26DD4865476BDA1 4: IDP 
RolesPep.evaluate(), policy trace: 
~~RL~O~~~~Rule Count: 1~~Success(67) 
~~RU~RuleID_1181251958207~Manager~DNF~~1:1~~Success (67) 
~~CS~1~~ANDsS~~1~~False(68) 
~~C0~1~LdapGroup(6645) :no-param:hidden-value:~ldap-group-is-member - 
of~SelectedLdapGroup( 66455) :hidden-param: hidden- value: ~~~False(68) 
</amLogEntry> 


This trace describes the following about the policy. 


1. The RL trace indicates that the policy has one rule and that the policy evaluated without error. 


2. The RU trace indicates that the rule (RuleID_1181251958207) has one condition and one action 
and that the rule evaluated without error. 


3. The CS trace indicates that the condition set evaluated to False (the user logging in does not 
match the conditions of the set). 


4. The CO trace indicates that the condition evaluated to False (the user logging in does not match 
the condition). 
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When you are troubleshooting why a user is not granted access to a resource that uses a role in its 

Authentication policy, the first step should be to look at Identity Server file and determine whether the 
user was assigned the role. In this trace, you can see that the user was not assigned the role. To fix 

this problem, you can either change the conditions of the Role policy to match the user or change the 
user's information so that the user matches the existing condition in the Role policy. 


When the Role Policy Is Not Enabled 


Sometimes a Role policy is created, but the Role policy is not enabled for Identity Server. When this 
happens, the trace looks similar to the following: 


<amLogEntry> 2009-06-11T16:06:03Z INFO NIDS Application: AM#500199050: 
AMDEVICEID#9921459858EAAC29: AMAUTHID#FDE680ABE320B682038947EA5F59D6B F: IDP 
RolesPep.evaluate(), policy trace: 

~~RL~@~~~~Rule Count: @~~Success(67) 
</amLogEntry> 


When you see Role policy traces that contain only the RL trace line, you need to enable the Role 
policy. 


When an Authorization Policy Uses a Role 


When a user requests access to a resource that has an Authorization policy that uses a role, the user 
is checked for the role assignment. The trace of this evaluation is in the ESP log file of Access 
Gateway that is processing the request. Such a trace looks similar to the following: 


<amLogEntry> 2009-07-13T22:13:29Z INFO NIDS Application: AM#501102050: 
AMDEVICEID#esp-51A474B83BFDDF4F: AMAUTHID#4538DB6F6E2A237FDE674FOC6E1 6DCEC: 
PolicyID#N748097P - 3507 -3KP7-4241-410PN4152094: NXPESID#1718: AGAuthorization 
Policy Trace: 
~~RL~1~~~~Rule Count: 1~~Success(0) 
~~RU~RuleID_1182876316974~Allow_Sales~DNF~~1:1~~Success(Q) 
~~CS~1~~ANDS~NOT~1~~True(69) 
~~C0~1~CurrentRoles (6660) :no-param:authenticated~com.novell.nxpe. 
condition.NxpeOperator@string-substring~SelectedRole( 6661) :hidden-param:hidden- 
value: ~~~False(68) 
~~PA~1~~Deny Access Messasge~Sorry, you must work in sales today.~~~Success(Q) 
~~PC~1~~Document=(ou=xpem1PEP, ou=mastercdn, ou=ContentPublisherCon 
tainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, 
o=novell: romaContentCollectionXMLDoc),Policy=(Allow_Sales),Rule=(1: :RuleID_1182876 
316974), Action=(Deny: :1)~~~~Success(0) 
</amLogEntry> 


This trace is for a Deny policy that denies access if the user has not been assigned the Sales role. 
The CO line indicates that the condition is looking for a role and that the user did not match the 
condition. 


The CS line indicates that the condition is a negative condition, meaning that the user matches the 
condition set when the user does not match the condition. This is the case for this user, so the 
condition set evaluates to True, and the action is then applied. 


The PA line describes the action that was applied. 
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30.16.2.4 


Identity Injection Traces 


The following traces explain what to look for in an Identity Injection policy that injects an authorization 
header: 


+ “When the User Has Authenticated” on page 1283 
e “When the User Has Not Authenticated” on page 1284 


When the User Has Authenticated 


The following trace is for an Identity Injection policy that successfully inserts an authentication header. 
The policy inserts LDAP credentials for the user’s name and password. Access Gateway injects the 
information, so the trace for this type of policy is in the ESP log file of Access Gateway. 


<amLogEntry> 2009-06-11T19:02:44Z INFO NIDS Application: AM#501103050: 
AMDEVICEID#esp -534FDODOE32FE4BD: AMAUTHID#61D5D5B3FF98156F8E4F2875981D 4AGE: 
PolicyID#51N4214K-74L1-491L-7190-2M9K04K21393: NXPESID#726: AGIdentityInjection 
Policy Trace: 

~~RL~O~~~~Rule Count: 1~~Success(67) 

~~RU~RuleID_1181251426062~basic_auth_ii~DNF~~0:1~~Success (67) 

~~PA~ActionID_1181251427701~~Inject Auth Header~uid~uid(1): 
CredentialProfile( 7010: ) :NEPXurn~3Anovell~3Acredentialprofile~3A2005- 
03~2Fcp~3ASecrets~2Fcp~3ASecret~2Fcp~3AEntry~40~40~40~40WSCQSSToken~40~40~40~40~2F 
cp~3ASecrets~2Fcp~3ASecret~5Bcp~3AName~3D~22LDAPCredentials~22~5D~2Fcp~3AEntry~5Bc 
p~3AName~3D~22UserName~22~5D : ~Ok~Success(0) 

~~PA~ActionID_1181251427701~~Inject Auth Header~password~pwd(1): 
CredentialProfile( 7010: ) :NEPXurn~3Anovell~3Acredentialprofile~3A2005- 
03~2Fcp~3ASecrets~2Fcp~3ASecret~2Fcp~3AEntry~40~40~40~40WSCQSSToken~40~40~40~40~2F 
cp~3ASecrets~2Fcp~3ASecret~5Bcp~3AName~3D~22LDAPCredentials~22~5D~2Fcp~3AEntry~5Bc 
p~3AName~3D~22UserPassword~22~5D : ~Ok~Success 
(0) 

~~PC~ActionID_1181251427701~~Document=(ou=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=a 
ccessManagerContainer, o=novell: romaContentCollectionXMLDoc),Policy=(basic_auth_ii) 
,RULe=(1: :RulLeID_1181251426062), Action=(InjectAuthHeader : :ActionID_1181251427701)~ 
~~~Success(0) 
</amLogEntry> 


<amLogEntry> 2009-06-11T19:02:44Z INFO NIDS Application: AM#501101021: 
AMDEVICEID#esp -534FDODOE32FE4BD: AMAUTHID#61D5D5B3FF98156F8E4F2875981D 4AGE: 
PolicyID#51N4214K-74L1-491L-7190-2M9K04K21393: NXPESID#726: Response sent: Status 
- success </amLogEntry> 


Each identity injection policy generates two log entries. The first entry indicates whether the policy 
could successfully retrieve the information and inject it into the header. The second entry specifies 
whether the response is successfully sent to the Web server. 


This first log entry describes the following about this policy: 
1. In the correlation tags (AM... tags), notice the ID assigned to the authenticated user making the 
request (AMAUTHID#61D5D5B3FF98156F8E4F2875981D4AGE). 


2. After the correlation tags, the trace specifies the ID of the policy (51N4214K-74L1-491L -7190- 
2M9KO04K21393). 


3. The RU trace indicates that the policy name is basic_auth_ii, that the policy has no conditions, 
and that the policy has one action rule. 


4. The first PA trace indicates that the uid (called LDAP User Name in the UI) of the Credential 
Profile has been successfully retrieved. 
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30.16.2.5 


5. The second PA trace indicates that the password of the Credential Profile has been successfully 
retrieved. 


6. The PC trace indicates that these items have been successfully injected into the header. 


You can use the user’s ID and the policy ID to find log entry that traces the response to the Web 
server. The second log entry indicates that the response was successfully sent to the Web server. 


When the User Has Not Authenticated 


If the user has not authenticated and therefore has no authentication credentials, the trace for an 
Identity Injection policy with an authentication header looks similar to the following: 


<amLogEntry> 2009-06-11T20:16:51Z INFO NIDS Application: AM#501103050: 
AMDEVICEID#esp-534FDODOE32FE4BD: PolicyID#0L8659PL - 0K69 -ONON-0845-5PN113KM3842: 
NXPESID#2539: AGIdentityInjection Policy Trace: 

~~RL~O~~~~Rule Count: 1~~Success(67) 

~~RU~RuleID_1181251426062~basic_auth_ii~DNF~~0:1~~Success (67) 

~~PA~ActionID_1181251427701~~Inject Auth Header~uid~uid(1): 
CredentialProfile(7010: ) :NEPXurn~3Anovell~3Acredentialprofile~3A2005- 
03~2Fcp~3ASecrets~2Fcp~3ASecret~2Fcp~3AEntry~40~40~40~40WSCQSSToken~40~40~40~40~2F 
cp~3ASecrets~2Fcp~3ASecret~5Bcp~3AName~3D~22LDAPCredentials~22~5D~2Fcp~3AEntry~5Bc 
p~3AName~3D~22UserName~22~5D : ~Ok~Success(0) 

~~PA~ActionID_1181251427701~~Inject Auth 
Header~password~pwd(1):CredentialProfile( 7010: ) :NEPXurn~3Anovell~3Acredentialprofi 
le~3A2005 -03~2Fcp~3ASecrets~2Fcp~3ASecret~2Fcp~3AEntry 
~40~40~40~40WSCQSSToken~40~40~40~40~2Fcp~3ASecrets~2Fcp~3ASecret~5Bcp~3AName~3D~22 
LDAPCredentials~22~5D~2Fcp~3AEntry~5Bcp~3AName~3D~22UserPassword~22~5D : ~Ok~Success 
(0) 

~~PC~ActionID_1181251427701~~Document=(ou=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=a 
ccessManagerContainer, o=novell: romaContentCollectionXMLDoc),Policy=(basic_auth_ii) 
,RULe=(1: :RuleID_1181251426062) , Action=(InjectAuthHeader : :ActionID_1181251427701)~ 
~~~Success(0) 
</amLogEntry> 


<amLogEntry> 2009-06-11T20:16:51Z INFO NIDS Application: AM#501101021: 
AMDEVICEID#esp-534FDODOE32FE4BD: PolicyID#0L8659PL - 0K69 - ONON-0845-5PN113KM3842: 
NXPESID#2539: Response sent: Status - success </amLogEntry> 


These entries look very similar to the entries for a successful injection of data. This is because 
injecting NULL data for data that is not available is considered a successful action. The trace displays 
data unavailable errors only when errors occur retrieving data. The key to determining whether the 
data was available for injection into an authentication header is to look for the AMAUTHID correlation 
tag in the log entry. The log entries for the OL8659PL - OK69 - ONON- 0845 -5PN113KM3842 policy do not 
contain an AMAUTHID correlation tag, which indicates that the user is not logged in. 


Authorization Traces 


Authorization policies for a protected resource might require a user to be authenticated before the 
data required by the policy can be obtained, but Authorization policies can be configured to use data 
that is available without authentication. The following traces show how the log entries for an 
Authorization policy trace are slightly different when the user is not authenticated. 


+ “When the Protected Resource Requires Authentication” on page 1285 
+ “When the Protected Resource Does Not Require Authentication” on page 1286 


For a trace of an Authorization policy that uses a role, see “When an Authorization Policy Uses a 
Role” on page 1282. 
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When the Protected Resource Requires Authentication 


The following is a successful trace of an Authorization policy that requires the user to have the value 
of Manager in the title attribute. To obtain this data, the user must be authenticated. 


The policy contains two rules: a Permit rule if the user has the value of Manager in the title attribute, 
and a Deny rule that denies all other users. This policy has been assigned to protect an Access 
Gateway resource. 


<amLogEntry> 2009-08-02T15:55:05Z INFO NIDS Application: AM#501101050: 
AMDEVICEID#esp -2FA73CE1A376FD91: Policy1D#45908443 -N8P5-KO21-680M-K172P107N405: 
NXPESID#1743: Evaluating policy </amLogEntry> 


<amLogEntry> 2009-08-02T15:55:06Z INFO NIDS Application: AM#501102050: 
AMDEVICEID#esp -2FA73CE1A376FD91: AMAUTHID#838976482579AF372C31C4727 4E9CB28: 
Policy1D#45908443 -N8P5-K021-680M-K172P107N405: NXPESID#1743: AGAuthorization 
Policy Trace: 
~~RL~1~~~~Rule Count: 2~~Success(0) 
~~RU~RuleID_1186068489688~Title_auth~DNF~~1:1~~Success(0) 
~~CS~1~~ANDsS~~1~~True(69) 
~~C0~1~LdapAttribute( 6647 ) : NEPXurn~3Anovel1~3Aldap~3A2006 - 
02~2Fldap~3AUserAttribute~40~40~40~40WSCQLDAPToken~40~40~40~40~2FUserAttribute~5B~ 
40ldap~3AtargetAttribute~3D~22title~22~5D : hidden- 
value:~com.novell.nxpe.condition.NxpeOperator@string-equals~(@) :hidden- 
param: hidden-value:~~~True(69) 
~~PA~1~~Permit Access~~~~Success(0) 
~~PC~1~~Document=(ou=xpem1PEP, ou=mastercdn, ou=ContentPublisher 
Container, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContain 
er, o=novell: romaContentCollectionXMLDoc),Policy=(Title_auth),Rule=(1: :RuleID_11860 
68489688) , Action=(Permit: :1)~~~~Success(0) 
</amLogEntry> 


<amLogEntry> 2009-08-02T15:55:06Z INFO NIDS Application: AM#501101021: 
AMDEVICEID#esp -2FA73CE1A376FD91: AMAUTHID#838976482579AF372C31C47274E 9CB28: 
Policy1D#45908443 -N8P5-K021-680M-K172P107N405: NXPESID#1743: Response sent: Status 
- success </amLogEntry> 


The first log entry is the request to evaluate the policy. The second log entry is the evaluation of the 
policy. The third log entry is the response that is returned. These three log entries can be tied together 
by using the following tags: 


AMDEVICEID#esp-2FA73CE1A376FD91: When a policy evaluation request is made, the same ESP 
processes the request. Even if Access Gateways are clustered, the policy evaluation request stays 
with Access Gateway that initiated the request. 


PolicyID#45908443-N8P5-KO21-680M-K172P107N405: Each policy is assigned a unique ID, and 
this is the ID assigned to the policy called Title_auth in Administration Console. To search for all log 
entries for a policy, use the policy ID. To search for log entries that evaluate the policy, use the policy 
name. 


AMAUTHID#838976482579AF372C31C47274E9CB28: The request to evaluate a policy does not 
contain the ID of the user the request is being made for, but the log entries for the evaluation and for 
the response status always contain the ID of an authenticated user. If the policy can be evaluated 
without the user being authenticated, these entries do not contain the ID of the user. This kind of 
policy might be assigned to a public resource (no authentication required) and use the time of day 
condition or day of the week condition for its evaluation criteria. See “When the Protected Resource 
Does Not Require Authentication” on page 1286. 
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When the Protected Resource Does Not Require Authentication 


The following trace is for an Authorization policy that uses data that is available without 
authentication. Authorization policies support a number of these conditions, such as Current Date, 
Current Day of Week, Current Day of Month, Current Time Of Day, Client IP, and the URL conditions. 
As long as you do not select to compare what is currently in the HTTP request with a value that 
requires authentication (such as LDAP attribute), the Authorization policy can be evaluated for an 
unauthenticated user. The following trace is for a policy with a Current Time of Day condition. The 
protected resource does not require authentication, so everyone can access the resource if their 
request comes in between 8:00 am and 5:30 pm, local time. 


<amLogEntry> 2009-08-03T16:30:48Z INFO NIDS Application: AM#501101050: 
AMDEVICEID#esp -2FA73CE1A376FD91: PolicyID#216660PM-429P -0660-N25N-L58LO8MN4N5M: 
NXPESID#4515: Evaluating policy </amLogEntry> 


<amLogEntry> 2009-08-03T16:30:48Z INFO NIDS Application: AM#501102050: 
AMDEVICEID#esp -2FA73CE1A376FD91: PolicyID#216660PM-429P -0660-N25N-L58LO8MN4N5M: 
NXPESID#4515: AGAuthorization Policy Trace: 
~~RL~1~~~~Rule Count: 2~~Success(0) 
~~RU~RuleID_1186082720202~time_of_day~DNF~~1:1~~Success(0) 
~~CS~1~~ANDs~~1~~True(69) 
~~CO~0~TimeOfDay(1005):::Fri Aug 03 10:30:48 MDT 
2007(9:30):~com.novell.nxpe.condition.NxpeOperator@time-in- 
range~(@)::::~~~True(69) 
~~PA~1~~Permit Access~~~~Success(0) 
~~PC~1~~Document=(ou=xpem1PEP, ou=mastercdn, ou=ContentPublisherCon 
tainer, ou=Partition, ou=PartitionsContainer, ou=VCDN_Root, ou=accessManagerContainer, 
o=novell: romaContentCollectionXMLDoc), Policy=(time_of_day),Rule=(1: :RuleID_1186082 
720202), Action=(Permit: :1)~~~~Success(0) 
</amLogEntry> 


<amLogEntry> 2009-08-03T16:30:48Z INFO NIDS Application: AM#501101021: 
AMDEVICEID#esp -2FA73CE1A376FD91: PolicyID#216660PM-429P -0660-N25N-L58LO8MN4N5M: 
NXPESID#4515: Response sent: Status - success </amLogEntry> 


The first log entry is the request to evaluate the policy. The second log entry is the evaluation of the 
policy, and from it you can tell that the user is not authenticated because the AMAUTHID# tag is 
missing. The third log entry is the response that is returned, and it indicates that a success was 
returned. The user is allowed access to the resource. 


Form Fill Traces 


The following sections describe how to enable logging for the Form Fill policies, describe the form 
that was used to create the Form Fill trace, then describe the entries that can be found in the logs: 
¢ “Enabling Form Fill Logging” on page 1287 
¢ “Sample Form and Policy Used for the Trace” on page 1287 
e “Embedded Service Provider Trace” on page 1289 
+ “Proxy Service Trace” on page 1290 
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Enabling Form Fill Logging 
Two modules evaluate the Form Fill policy and log entries: 


+ Embedded Service Provider (ESP) of Access Gateway evaluates the Form Fill policy and logs 
entries to its file. ESP sends the messages to the catalina. out file (Linux) or the stdout .1log 
file (Windows) of Access Gateway. To enable ESP logging, see Section 21.6, “Turning on 
Logging for Policy Evaluation,” on page 1062. 


+ The proxy service of Access Gateway reports on the process of finding the form data and filling it 
in. 


For Access Gateway Appliance, see the /var/log/novell-apache2/soapmessages file. 


You can configure a custom filter and file to log Form Fill entries. For the filter, enable the Form 
Fill Processing events in the Advanced Log Level Options section. 


Sample Form and Policy Used for the Trace 
Figure 30-10 illustrates the simple form that was used for the trace. 


Figure 30-10 Form Used for the Trace 


Novell Services Login 


Username: 


Password: 


title: 


Source HTML for the Form 
The name of the form and the fields that need to be filled in by the policy are in bold typeface. 


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<html> 


<head> 
<meta http-equiv="Content-type" content="text/html; charset=utf-8"> 
<title>kelly</title> 
</head> 
<body> 
<form name="mylogin" action="double.php" method="post" id="mylogin"> 
<center> 
<table border="0" cellpadding="4" cellspacing="4" width="570"> 
<tr> 
<td width="121" height="285" align="left" valign="top"> 
</td> 


<td width="449" height="285" align="center" valign="top"> 
<p align="center"> 
<font size="5">Novell Services Login<br></font> 
</p> 
<table border="0" width="86%"> 
<tr> 
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<td width="25%">Username: </td> 
<td width="75%"> 
<input type="TEXT" name="username"> 
</td> 
</tr> 
<tr> 
<td width="25%">Password:</td> 
<td width="75%"> 
<input type="PASSWORD" name="password" size="30"> 
</td> 
</tr> 
<tr> 
<td width="25%">title:</td> 
<td width="75%"> 
<input type="TEXT" name="title" size="30"> 
</td> 
</tr> 
</table> 
</td> 
</tr> 


<tr> 
<td colspan="2" align="center"> 
<input type="hidden" name="formNum" value="1"> 
<input type="submit" value="Login"> 
<input type="reset"> 
</td> 
</tr> 
</table> 
</center> 
</form> 
</body> 
</html> 


Form Fill Policy 


The following Form Fill policy was created for the mylogin form. The policy is called Form_Fill. You 
can use the name of the policy to find entries for it in the log files. The policy was assigned to the / 
identity/forms/simple.html protected resource. Because the URL path identifies a specific file 
on the Web server, the policy does not require any CGI or page matching criteria. 
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Figure 30-11 The Form Fill Policy for the mylogin Form 


Actions 


New w 


Do Form Fill Form Selection 
Form Name © i [mylogin 
CGI Matching Criteria w [No items] 
Page Matching Criteria W [No items] 
Fill Options 
New 
Input Field Name Input Field Type Input Field Value 


Data Conversion 


username Text v Credential Profile © : LDAP Credentials:LDAP User Name w [None] Y 
[password | Password w Credential Profile ¥ : LDAP Credentials:LDAP Password œ [None] Y 
title | Text ¥ LDAP Attribute ¥ ; title ¥ [None] ¥ 


Submit Options 
Auto Submit 
C Debug Mode 
O Mask Data 

CO Insert Text in Header 
Text to Insert w [No items] 

CO Enable JavaScript Handling 
Functions to Keep w [No items] 
Statements to Execute on Submit W [No items] 

Error Handling 

Redirect to URL: 


This policy is configured so that the user never sees the form. Even on first login, the form is filled in 
for authenticated users because the user’s authentication credentials are used for the username and 
password fields, and the title field value is obtained from the LDAP user store. If the user does not 

have a value for the title attribute, the user sees the form every time the page is accessed. If you want 


the value to be saved for these users, you need to change the policy to use a secret store rather than 
an LDAP attribute. 


Embedded Service Provider Trace 


When you look for entries for the Form_Fill policy in the Embedded Service Provider trace, you can 
use the following strings to find the entries: 


+ The name of the Form Fill policy: Form_Fill 
¢ The string identifying a Form Fill trace: AGFormFill Policy Trace 
+ The policy ID (after you have found it): PolicyID#0600287L -@6LO-KKP4-207M-6971PPM6147L 


The following trace is from the catalina. out file of the Embedded Service Provider of an Access 
Gateway Appliance. The entries have been numbered so that they can be described, and a few extra 
line breaks and spaces have been added to make the entries easier to read. 
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1. <amLogEntry> 2009-09-14T00:15:52Z INFO NIDS Application: AM#501101050: 
AMDEVICEID#esp-917A1174C8A270FC: PolicyID#0600287L-0O6LO-KKP4-207M-6971PPM6147L: 
NXPESID#2663: Evaluating policy </amLogEntry> 


2. <amLogEntry> 2009-09-14T00:15:52Z INFO NIDS Application: AM#501104050: 
AMDEVICEID#esp-917A1174C8A270FC: PolicyID#0600287L-0O6LO-KKP4-207M-6971PPM6147L: 
NXPESID#2663: AGFormFill Policy Trace: 
~~RL~1~~~~Rule Count: 1~~Success(67) 
~~RU~RuleID_1189711482510~Form_Fil1l~DNF~~0:1~~Success(67) 
~~PA~ActionID_1189711485006~~Added Form Selection Group~~~~Success 
(0) 
~~PA~ActionID_1189711485006~~Added Fill Options Group~~~~Success(0) 
~~PA~ActionID_1189711485006~~Added Submit Options Group~~~~Success 
(0) 
~~PC~ActionID_1189711485006~~Document=(ou=xpem1PEP, ou=mastercdn, 
ou=ContentPublisherContainer, ou=Partition, ou=PartitionsContainer, 
ou=VCDN_Root, ou=accessManagerContainer, o=novell: romaContent 
CollectionXMLDoc), Policy=(Form_Fill), Rule=(1: :RuleID_11897114 
82510), Action=(FormFill: :ActionID_1189711485006 )~~~~Success(0) 
</amLogEntry> 


3. <amLogEntry> 2009-09-14T00:15:52Z INFO NIDS Application: AM#501101021: 
AMDEVICEID#esp-917A1174C8A270FC: PolicyID#0600287L-0O6LO-KKP4-207M-6971PPM6147L: 
NXPESID#2663: Response sent: Status - success </amLogEntry> 


1. The first log entry is the request to evaluate the policy. If this entry does not’ occur, ensure that 
the Form Fill policy is enabled for the protected resource. 


2. The second entry is the actual policy trace. For a Form Fill policy, it is fairly basic information 
about the three types of actions in the policy: matching the form, filling in the field options, and 
adding the submit options. To determine what information was put in the options, you need to 
view the proxy service trace. 


3. The third entry indicates the type of response that is returned from the evaluation. In this entry, 
success is returned. 
Proxy Service Trace 


When you look for entries in the proxy trace of Access Gateway log, you can use the following strings 
to find the entries: 


+ The name of the Form Fill policy: Form_Fill 
+ The name of the form: mylogin 
+ The names of the fill option fields: username, password, title 


The sample trace is from the error_log file of aAccess Gateway Appliance. Some of the lines are 
very long, and extra white space has been added to make them easier to read. 
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30.16.3 


30.16.3.1 


Sep 9 17:05:08 nam40-mag1 httpd[16354]: [warn] AMEVENTID#40: FF:fillSilent: 
mastercdnForm_Fil13310 

Sep 9 17:05:08 nam40-mag1 httpd[16354]: [warn] AMEVENTID#40: FF:Filling: username 
Sep 9 17:05:08 nam40-mag1 httpd[16354]: [warn] AMEVENTID#40: FF:Filling: password 
Sep 9 17:05:08 nam40-mag1 httpd[16354]: [warn] AMEVENTID#40: FF:Filling: title 
Sep 9 17:05:08 nam40-magi httpd[16354]: [warn] AMEVENTID#40: FF: No Match 
<formNum> 

Sep 9 17:05:08 nam40-mag1 httpd[16354]: [warn] AMEVENTID#40: FF:fillInteractive 
FormFill Policy :mastercdnForm_Fil13310 Inject JavaScript Policy: 
mastercdnForm_Fil13510 

Sep 9 17:05:08 nam40-mag1 httpd[16354]: [warn] AMEVENTID#42: FF:fillSilent: 
mastercdnForm_Fil13310, referer: http://www.ag1.com/identity/forms/simple. html 

Sep 9 17:05:08 nam40-magi httpd[16354]: [warn] AMEVENTID#42: FF:Not Found: <form>, 
referer: http://www.agi.com/identity/forms/simple. html 

Sep 9 17:05:08 nam40-mag1 httpd[16354]: [warn] AMEVENTID#42: FF:no <Form 
pol:mastercdnForm_Fil13310, referer: http://www.ag1.com/identity/forms/simple. html 


On Access Gateway Appliance, you can get more detailed information about the process that was 
used to fill the form when you turn on logging to the soapmessages file. 


Adding Hashed Cookies into Browsers 


With security improvements in the 4.3 release, all Access Manager session cookies have been 
hashed to avoid potential session hijacks from someone with access to log files. As a result of this, 
troubleshooting became difficult as the tracking of a user session on the browser could not be 
transparently mapped to an entry on the server side logs. 


To address this issue, Access Manager 4.3 Service Pack 1 introduces advanced options to set the 
hashed cookie on the browser. With this in place, it is easier to map the Access Manager session 
cookies to the corresponding log files. 


¢ Section 30.16.3.1, “Adding Hashed Identity Server Cookies into Browsers,” on page 1291 
¢ Section 30.16.3.2, “Adding Hashed Access Gateway Cookies into Browsers,” on page 1292 
¢ Section 30.16.3.3, “Adding Hashed ESP Cookies into Browsers,” on page 1292 


Adding Hashed Identity Server Cookies into Browsers 


1 Open the web.xml file. 

Linux: /opt/novell/nids/1lib/webapp/WEB- INF/ 

Windows: \Program Files (x86)\Novell\Tomcat \webapps\nidp\WEBINF\ 
2 Uncomment the following configuration: 


<filter> 
<filter -name>DebugFilter</filter -name> 
<description> Filter to set the masked cookies in http response for 
debugging purpose.</description> 
<filter- 
class>com.novell.nidp.servlets.filters.debug.MaskedCookiesSetter</filter - 
class> 
</filter> 
<filter -mapping> 
<filter -name>DebugFilter</filter -name> 
<url-pattern>/*</url-pattern> 
</filter-mapping> 
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30.16.3.2 


30.16.3.3 


30.17 


3 Restart Identity Server. 


Identity Server sets the HJSESSIONID cookie in the browser containing the same hashed value 
as that in the log references to a session. 


Adding Hashed Access Gateway Cookies into Browsers 


When you set the NAGGlobalOptions SetHashedCookiesInResponse=on advanced option, Access 
Gateway sets these hashed values of IPC cookies and AGIDC cookies into the browser with the 
name IPCZQX0354154289-Hash and AGIDC0354154289-Hash. 


Perform the following steps: 


1 Click Devices > Access Gateways > Edit > Advanced Options. 


2 Set NAGGlobalOptions SetHashedCookiesInResponse=on. 


Adding Hashed ESP Cookies into Browsers 


1 Open the web.xml file. 

Linux: /opt/novell/nesp/1lib/webapp/WEB- INF/ 

Windows: \Program Files (x86)\Novell\Tomcat \webapps\nesp\WEBINF\ 
2 Uncomment the following configuration: 


<filter> 
<filter -name>DebugFilter</filter -name> 
<description> Filter to set the masked cookies in http response for 
debugging purpose.</description> 
<filter- 
class>com.novell.nidp.servlets.filters.debug.MaskedCookiesSetter</filter - 
class> 
</filter> 
<filter -mapping> 
<filter -name>DebugFilter</filter -name> 
<url-pattern>/*</url-pattern> 
</filter-mapping> 


3 Restart ESP. 


ESP sets the HJSESSIONID cookie in the browser containing the same hashed value as that in 
the log references to a session. 


Access Manager Audit Events and Data 


This section contains all the audit events logged by Access Manager. Each event has EventID, 
Description, Originator Title, Target Title, Subtarget Title, Text1 Title, Text2 Title, Text3 Title, Value’ 
Title, Value1 Type, Group Title, Data Length, and Data Type values stored. Each field contains a 
single character token (such as B, U, Y, and so on) that represent the data fields of the audit event, 
with each letter representing a different data field. The mapping of the character tokens to data fields 
is found in the nids_en.1scfile. 


Audit events are device-specific. You can select events for the following devices: 


+ Administration Console: In Administration Console Dashboard, click Auditing. 
¢ Identity Server: Click Devices > Identity Servers > Edit > Auditing and Logging. 


+ Access Gateway: Click Devices > Access Gateways > Edit > Auditing. 
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JavaScript Object Notation (JSON) Event Format 
Sample JSON Format 


This event is generated when you select the Risk-Based Authentication Succeeded option under 
Audit Logging on the Logging page of an Identity Server configuration. 


The following is a sample JSON event format of a Risk-Based authentication: 


{ 

"appName" : "Novell Access Manager", 

"Component" : "nidp", 

"timeStamp" : "Fri, 31 Jul 2015 17:30:57 +0530", 

"eventId" : "002E0025", 

"Description": "NIDS: Risk based additional authentication executed successfully 
for user", 

"Originator": "9772686A5705BA6C", 

"Target": "cn=admin, o=novell", 


"SubTarget": "3883A05A302BA3BDC7899AF05810B08B", 
"stringValuei": "35", 


"stringValue2": "medium", 
"stringValue3": "null", 
"numericValuei": "0", 
"numericValue2": "0", 
"numericValue3": "0", 


"Data": "MTYOLJK5LJEZNy41Mg==", 

"Message": "[Fri, 31 Jul 2015 17:30:57 +0530] [Novell Access Manager\nidp]: 
AMDEVICEID#9772686A5705BA6C: AMAUTHID#3883A05A302BA3BDC7899AF05810B08B: Risk based 
authentication successful for user: [cn=admin, o=novell]. RiskScore: [35] RiskLevel: 
[Medium] Additional authentication class: [$SF] Client IP Address: 
[164.99.137.52]", 


} 


The following table lists the event fields with its corresponding description: 


Field Description 
appName Specifies the name of the product. 
Component Specifies the name of the Access Manager component. For example, “nipd” identifies 


that the audit is triggered by Identity Server. 


timeStamp Specifies the time when the event occurred. 


eventid Specifies the event ID. For example, 002E0025. To view all the events and their 
corresponding event IDs, see the below sections. 


Description Describes the event. 


Originator Specifies the ID of the device that generated this event. For example, 
9772686A5705BA6C is the device with ID “idp-9772686A5705BA6C” 


Target Specifies the target on which this action is executed. In the above example, the action 
is risk-based authentication, hence the target is the user id for which the risk was 
assessed. 

SubTarget Specifies the additional details about the target. 

stringValue1 Specifies an event-specific string value. The value of this field varies from event to 


event. For example, it is null if the event has no value to pass. 
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Field Description 


stringValue2 Specifies an event-specific string value. The value of this field varies from event to 
event. For example, it is null if the event has no value to pass. 


stringValue3 Specifies an event-specific string value. The value of this field varies from event to 
event. For example, it is null if the event has no value to pass. 


numbericValue1 Specifies an event-specific string value. The value of this field varies from event to 
event. For example, it is null if the event has no value to pass. 


numbericValue2 Specifies an event-specific string value. The value of this field varies from event to 
event. For example, it is null if the event has no value to pass. 


numbericValue3 Specifies an event-specific string value. The value of this field varies from event to 
event. For example, it is null if the event has no value to pass. 


Data Specifies an event-specific data. 


Message Specifies a friendly detailed message related to the event. 


NOTE: The Syslog agents use the following message format: rfc3164. For more information, see 
RFC 3164 documentation. 


This section discusses the following audit events: 


¢ Section 30.17.1, “NIDS: Sent a Federate Request (002e0001),” on page 1297 

¢ Section 30.17.2, “NIDS: Received a Federate Request (002e0002),” on page 1297 

e Section 30.17.3, “NIDS: Sent a Defederate Request (002e0003),” on page 1297 

¢ Section 30.17.4, “NIDS: Received a Defederate Request (002e0004),” on page 1298 

¢ Section 30.17.5, “NIDS: Sent a Register Name Request (002e0005),” on page 1298 

¢ Section 30.17.6, “NIDS: Received a Register Name Request (002e0006),” on page 1299 


¢ Section 30.17.7, “NIDS: Logged Out an Authentication that Was Provided to a Remote 
Consumer (002e0007),” on page 1299 


¢ Section 30.17.8, “NIDS: Logged out a Local Authentication (002e0008),” on page 1300 


¢ Section 30.17.9, “NIDS: Provided an Authentication to a Remote Consumer (002e0009),” on 
page 1300 


¢ Section 30.17.10, “NIDS: User Session Was Authenticated (002e000a),” on page 1301 


+ Section 30.17.11, “NIDS: Failed to Provide an Authentication to a Remote Consumer 
(002e000b),” on page 1301 


¢ Section 30.17.12, “NIDS: User Session Authentication Failed (002e000c),” on page 1302 

¢ Section 30.17.13, “NIDS: Received an Attribute Query Request (002e000d),” on page 1302 
¢ Section 30.17.14, “NIDS: User Account Provisioned (002e000e),” on page 1303 

¢ Section 30.17.15, “NIDS: Failed to Provision a User Account (002e000f),” on page 1303 

¢ Section 30.17.16, “NIDS: Web Service Query (002e0010),” on page 1304 

¢ Section 30.17.17, “NIDS: Web Service Modify (002e0011),” on page 1305 

¢ Section 30.17.18, “NIDS: Connection to User Store Replica Lost (002e0012),” on page 1305 


¢ Section 30.17.19, “NIDS: Connection to User Store Replica Reestablished (002€0013),” on 
page 1306 


¢ Section 30.17.20, “NIDS: Server Started (002e0014),” on page 1306 
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Section 30.17.21, “NIDS: Server Stopped (002e0015),” on page 1307 

Section 30.17.22, “NIDS: Server Refreshed (002e0016),” on page 1307 

Section 30.17.23, “NIDS: Intruder Lockout (002e0017),” on page 1308 

Section 30.17.24, “NIDS: Severe Component Log Entry (002e0018),” on page 1308 
Section 30.17.25, “NIDS: Warning Component Log Entry (002e0019),” on page 1309 


Section 30.17.26, “NIDS: Failed to Broker an Authentication from Identity Provider to Service 
Provider as Identity Provider and Service Provider Are not in Same Group (002E001A),” on 
page 1309 


Section 30.17.27, “NIDS: Failed to Broker an Authentication from Identity Provider to Service 
Provider Because a Policy Evaluated to Deny (002E001B),” on page 1310 


Section 30.17.28, “NIDS: Brokered an Authentication from Identity Provider to Service Provider 
(002E001C),” on page 1310 


Section 30.17.29, “NIDS: OAuth2 Authorization code issued (002e0028),” on page 1311 
Section 30.17.30, “NIDS: OAuth2 token issued (002e0029),” on page 1311 

Section 30.17.31, “NIDS: OAuth2 Authorization code issue failed (002e€0030),” on page 1312 
Section 30.17.32, “NIDS: OpenID token issued (002e0031),” on page 1312 

Section 30.17.33, “NIDS: OAuth2 refresh token issued (002€0032),” on page 1312 

Section 30.17.34, “NIDS: OAuth2 token issue failed (002e€0033),” on page 1313 

Section 30.17.35, “NIDS: OpenID token issue failed (002e0034),” on page 1313 

Section 30.17.36, “NIDS: OAuth2 refresh token issue failed (002e0035),” on page 1314 


Section 30.17.37, “NIDS: OAuth2 client has been registered successfully (002e0036),” on 
page 1314 


Section 30.17.38, “NIDS: OAuth2 client has been modified successfully (002e0037),” on 
page 1315 


Section 30.17.39, “NIDS: OAuth2 client has been deleted successfully (002€0038),” on 
page 1315 


Section 30.17.40, “NIDS: OAuth2 user has provided consent (002e0039),” on page 1316 
Section 30.17.41, “NIDS: OAuth2 user has revoked consent (002e0040),” on page 1316 
Section 30.17.42, “NIDS: OAuth2 token validation success (002e0041),” on page 1316 

Section 30.17.43, “NIDS: OAuth2 token validation failed (002e0042),” on page 1317 

Section 30.17.44, “NIDS: OAuth2 client registration failed (002e0043),” on page 1317 

Section 30.17.45, “NIDS: Roles PEP Configured (002e0300),” on page 1318 

Section 30.17.46, “NIDS: Risk-Based Authentication Action for User (002e0045),” on page 1318 
Section 30.17.47, “NIDS: Risk-Based Authentication Action for User (002e0046),” on page 1319 
Section 30.17.48, “NIDS: Risk-Based Authentication Action for User (002e0047),” on page 1319 
Section 30.17.49, “NIDS: Token was Issued to Web Service (002E001F),” on page 1320 
Section 30.17.50, “NIDS: Issued a Federation Assertion (002E0102),” on page 1320 

Section 30.17.51, “NIDS: Received a Federation Assertion (002E0103),” on page 1321 

Section 30.17.52, “Access Gateway: PEP Configured (002e0301),” on page 1321 

Section 30.17.53, “Roles Assignment Policy Evaluation (002e€0320),” on page 1322 

Section 30.17.54, “Access Gateway: Authorization Policy Evaluation (002e0321),” on page 1322 
Section 30.17.55, “Access Gateway: Form Fill Policy Evaluation (002e0322),” on page 1323 
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¢ Section 30.17.56, “Access Gateway: Identity Injection Policy Evaluation (002e0323),” on 
page 1323 


¢ Section 30.17.57, “Access Gateway: Access Denied (0x002e0505),” on page 1324 

+ Section 30.17.58, “Access Gateway: URL Not Found (0x002e0508),” on page 1324 

¢ Section 30.17.59, “Access Gateway: System Started (0x002e0509),” on page 1325 

¢ Section 30.17.60, “Access Gateway: System Shutdown (0x002e050a),” on page 1325 

+ Section 30.17.61, “Access Gateway: Identity Injection Parameters (0x002e050c),” on page 1326 
¢ Section 30.17.62, “Access Gateway: Identity Injection Failed (Ox002e050d),” on page 1327 

+ Section 30.17.63, “Access Gateway: Form Fill Authentication (0x002e050e),” on page 1327 


+ Section 30.17.64, “Access Gateway: Form Fill Authentication Failed (0Ox002e050f),” on 
page 1328 


¢ Section 30.17.65, “Access Gateway: URL Accessed (0x002e0512),” on page 1328 
+ Section 30.17.66, “Access Gateway: IP Access Attempted (0x002e0513),” on page 1329 
¢ Section 30.17.67, “Access Gateway: Webserver Down (0x002e0515),” on page 1330 


¢ Section 30.17.68, “Access Gateway: All WebServers for a Service is Down (0x002e0516),” on 
page 1330 


+ Section 30.17.69, “Access Gateway: Application Accessed (002E0514),” on page 1331 
¢ Section 30.17.70, “Access Gateway: Session Created (002E0525),” on page 1331 
+ Section 30.17.71, “Management Communication Channel: Health Change (0x002e0601),” on 


page 1332 

+ Section 30.17.72, “Management Communication Channel: Device Imported (0x002e0602),” on 
page 1332 

¢ Section 30.17.73, “Management Communication Channel: Device Deleted (0x002e0603),” on 
page 1333 


+ Section 30.17.74, “Management Communication Channel: Device Configuration Changed 
(Ox002e0604),” on page 1334 


¢ Section 30.17.75, “Management Communication Channel: Device Alert (0x002e0605),” on 
page 1334 


¢ Section 30.17.76, “Management Communication Channel: Statistics (00O2e0606),” on page 1335 
+ Section 30.17.77, “Risk-Based Authentication Successful (002e0025),” on page 1335 

¢ Section 30.17.78, “Risk-Based Authentication Failed (002e0026),” on page 1336 

+ Section 30.17.79, “Risk-Based Authentication for User (002e€0027),” on page 1336 

+ Section 30.17.80, “Impersonation Sign in (002E0048),” on page 1337 

¢ Section 30.17.81, “Impersonation: Impersonator Logs Out (002E0049),” on page 1337 

+ Section 30.17.82, “Impersonation: Session Started (002E0050),” on page 1338 

¢ Section 30.17.83, “Impersonation: Impersonatee Denies (002E0051),” on page 1338 

¢ Section 30.17.84, “Impersonation: Impersonatee Approves (002E0052),” on page 1339 
+ Section 30.17.85, “Impersonation: Impersonator Cancels (002E0053),” on page 1340 

¢ Section 30.17.86, “Impersonation: Authorization Policy Fails (002E0054),” on page 1340 
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30.17.1 


30.17.2 


30.17.3 


NIDS: Sent a Federate Request (002e0001) 


This event is generated when you select the Federation Request Sent option under Audit Logging on 
the Logging page of an Identity Server configuration. 


Description: NIDS: Sent a federate request. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: LDAP Auth: User DN Other Auth: User 
GUID 


SubTarget (Y): null 
Text1 (S): null 
Text2 (T): null 
Text3 (F): null 
Value! (1): 0 
Group (G): 0 
Data Length (X): 0 
Data (D): null 


NIDS: Received a Federate Request (002e0002) 


This event is generated when you select the Federation Request Handled option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Received a federate request. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: LDAP Auth: User DN Other Auth: User 
GUID 


SubTarget (Y): null 

Text1 (S): Schema Title: Provider Identifier; Data Description: Service Provider ID 
Text2 (T): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


NIDS: Sent a Defederate Request (002e0003) 


This event is generated when you select the Defederation Request Sent option under Audit Logging 
on the Logging page of an Identity Server configuration. 
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30.17.4 


30.17.5 


Description: NIDS: Sent a defederate request. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: LDAP Auth: User DN Other Auth: User 
GUID 


SubTarget (Y): null 

Text1 (S): Schema Title: Provider Identifier; Data Description: Service Provider ID 
Text2 (T): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


NIDS: Received a Defederate Request (002e0004) 


This event is generated when you select the Defederation Request Handled option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Received a defederate request 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: LDAP Auth: User DN Other Auth: User 
GUID 


SubTarget (Y): null 

Text1 (S): Schema Title: Provider Identifier Data Description: Service Provider ID 
Text2 (T): null 

Text3 (F): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


NIDS: Sent a Register Name Request (002e0005) 


Description: NIDS: Sent a register name request 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): null 
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Text1 (S): null 
Text2 (T): null 
Text3 (F): null 
Value1 (1): 0 
Group (G): 0 

Data Length (X): 0 
Data (D): null 


30.17.66 NIDS: Received a Register Name Request (002e0006) 


This event is generated when you select the Register Name Request Handled option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Received a register name request 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): null 
Text1 (S): null 
Text2 (T): null 
Text3 (F): null 
Value1 (1): 0 
Group (G): 0 

Data Length (X): 0 
Data (D): null 


30.17.7 NIDS: Logged Out an Authentication that Was Provided to a 
Remote Consumer (002e0007) 


This event is generated when you select the Logout Provided option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: Logged out an authentication that was provided to a remote consumer 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: LDAP Auth: User DN Other Auth: User 
GUID 


SubTarget (Y): null 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 
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30.17.8 


30.17.9 


Text2 (T): null 

Text3 (F): null 

Value1 (1): Schema Title: Timed Out Data Description: 0 = other reason 1 = timed out 
Group (G): 0 

Data Length (X): 0 

Data (D): null 


NIDS: Logged out a Local Authentication (002e0008) 


This event is generated when you select the Logout Local option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: Logged out a local authentication 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: LDAP Auth: User DN Other Auth: User 
GUID 


SubTarget (Y): null 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id: 


Text2 (T): null 

Text3 (F): null 

Value! (1): Schema Title: Timed Out Data Description: 0 = other reason 1 = timed out 
Group (G): 0 

Data Length (X): 0 

Data (D): null 


NIDS: Provided an Authentication to a Remote Consumer 
(002e0009) 


This event is generated when you select the Login Consumed option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: Provided an authentication to a remote consumer 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text1 (S): Schema Title: Authentication Type Data Description: Authentication Profile 


Text2 (T): Schema Title: Authentication Entity Name Data Description: Authentication Source 
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Text3 (F): Schema Title: Contract Class or Method Name Data Description: Authentication Contract 
URI 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


30.17.10 NIDS: User Session Was Authenticated (002e000a) 


This event is generated when you select the Login Provided option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: User session was authenticated 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) + IDP Ancestral session id if at all exists seperated by '-' 


Text1 (S): Schema Title: Authentication Type Data Description: Authentication Profile 
Text2 (T): Schema Title: Authentication Entity Name Data Description: Authentication Source 


Text3 (F): Schema Title: User Agent and Cluster Name Data Description: User agent and cluster 
name of IDP seperated by '-' 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


30.17.11 NIDS: Failed to Provide an Authentication to a Remote 
Consumer (002e000b) 


This event is generated when you select the Login Consumed Failure option under Audit Logging on 
the Logging page of an Identity Server configuration. 


Description: NIDS: Failed to provide an authentication to a remote consumer 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 
SubTarget (Y): null 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 
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Text2 (T): Schema Title: Provider Identifier Data Description: Service Provider ID 
Text3 (F): Schema Title: Reason Data Description: Reason Message 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


NIDS: User Session Authentication Failed (002e000c) 


This event is generated when you select the Login Provided Failure option under Audit Logging on 
the Logging page of an Identity Server configuration. Use the Description field and the Text3 (F) field 
to determine whether the failure came from a contract, SAML 1.1, SAML 2.0, or Liberty. 


Description: NIDS: User session authentication failed. This string plus one of the following 
phrases: for a contract failure, Contract Execution; fora SAML 1.1 failure, SAML Assertion; fora 
SAML 2.0 failure, SAML2 SSO; for a Liberty failure, Liberty SSO. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: Authentication Contract Name Data Description: Contract URI 
SubTarget (Y): Schema Title: User Identifier Data Description: User DN 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text2 (T): Schema Title: Reason Data Description: Reason Message 


Text3 (F): Schema Title: Authentication Source Data Description: Contains a JSON object 
comprising information such as user agent, cluster ID for Identity Server, service provider name, and 
PID. For a contract, contains the authentication method name; for Liberty, contains the service 
provider IP; for SAML 1.1, contains the SAML assertion issuer; for SAML 2.0, contains the service 
provider IP. 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication failed. 


NIDS: Received an Attribute Query Request (002e000d) 


This event is generated when you select the Attribute Query Request Handled option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Received an attribute query request 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 
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Target (U): Schema Title: User Identifier Data Description: LDAP Auth: User DN Other Auth: User 
GUID 


SubTarget (Y): null 

Text1 (S): Schema Title: Provider Identifier Data Description: Service Provider ID 
Text2 (T): Schema Title: Attribute Names Data Description: Requested Attributes 
Text3 (F): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


30.17.14 NIDS: User Account Provisioned (002e000e) 


This event is generated when you select the User Account Provisioned option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: NIDS: User account provisioned 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Store Identifier Data Description: Displayable user name 
SubTarget (Y): null 
Text1 (S): Schema Title: User Identifier Data Description: Authentication User Name 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): null 
Value! (1): 0 
Group (G): 0 
Data Length (X): 0 
Data (D): null 


30.17.15 NIDS: Failed to Provision a User Account (002e000f) 


This event is generated when you select the User Account Provisioned Failure option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Failed to provision a user account 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Store Identifier Data Description: Displayable User Name 


SubTarget (Y): null 
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Text1 (S): Schema Title: User Identifier Data Description: Authentication User Name 
Text2 (T): Schema Title: Reason Data Description: Reason Message 

Text3 (F): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


NIDS: Web Service Query (002e0010) 


This event is generated when you select the Web Service Query Handled option under Audit 
Logging on the Logging page of an Identity Server configuration. Identity Server uses this event for 
two types of Web service queries: 


¢ Discovery: This is a query to discover a service. For this type of query, the Group (G) field is not 
used. For a remote query, the Data Description of the Value1 field is set to 0. For a local query, 
the Data Description of the Value! field is set to 1. 


¢ Profile: This is a query to get attributes for a user from a profile (personal, credential, etc.). For 
this type of query, the Group (G) field contains a GroupingID for all attributes selected in the 
request. A separate event is generated for each attribute select list in the request. For a remote 
query, the Data Description of the Value! field is set to 0. For a local query, the Data Description 
of the Value1 field is set to 1. 


Description: NIDS: Web Service query 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 

SubTarget (Y): null 

Text1 (S): Schema Title: Provider Identifier Data Description: Requesting Provider ID 
Text2 (T): Schema Title: Select String Data Description: Requested attributes; select string 
Text3 (F): Schema Title: Service Identifier Data Description: Web Service URI 

Value! (1): Schema Title: Local Data Description: 0 - Remote 1 — Local 


Group (G): Schema Title: Query Group Data Description: If this is a profile query, it contains the 
grouping ID for all attributes selected in this request. Otherwise, this field is not used in the event. 


Data Length (X): 0 
Data (D): null 
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30.17.17 


30.17.18 


NIDS: Web Service Modify (002e0011) 


This event is generated when you select the Web Service Modify Handled option under Audit 
Logging on the Logging page of an Identity Server configuration. Identity Server uses this event for 
two types of Web service modify requests: 


¢ Discovery: This is a request to discover a service to modify. For this type of request, the Group 
(G) field is not used. For a remote request, the Data Description of the Value1 field is set to 0. 
For a local request, the Data Description of the Value’ field is set to 1. 


¢ Profile: This is a request to modify the attributes of a user in a profile (personal, credential, etc.). 
For this type of request, the Group (G) field contains a GroupingID for all attributes selected in 
the request. A separate event is generated for each attribute select list in the modify request. For 
a remote request, the Data Description of the Value! field is set to 0. For a local request, the 
Data Description of the Value! field is set to 1. 


Description: NIDS: Web Service modify 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 

SubTarget (Y): null 

Text1 (S): Schema Title: Provider Identifier Data Description: Requesting Provider ID 
Text2 (T): Schema Title: Select String Data Description: Modified attributes select string 
Text3 (F): Schema Title: Service Identifier Data Description: Web Service URI 

Value! (1): Schema Title: Local Data Description: 0 - Remote; 1 — Local 


Group (G): Schema Title: Modify Group Data Description: If this is a profile modify, it contains the 
grouping ID for each attribute select list in the request. Otherwise, this field is not used in the event. 


Data Length (X): 0 
Data (D): null 


NIDS: Connection to User Store Replica Lost (002e0012) 


This event is generated when you select the LDAP Connection Lost option under Audit Logging on 
the Logging page of an Identity Server configuration. 


Description: NIDS: Connection to user store replica lost 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Store Replica Name Data Description: Replica name 
SubTarget (Y): null 


Text1 (S): Schema Title: User Store Replica Host Data Description: IP Address of User Store replica 
server 


Text2 (T): null 
Text3 (F): null 


Troubleshooting 1305 


30.17.19 


30.17.20 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 
Data (D): null 


NIDS: Connection to User Store Replica Reestablished 
(002e0013) 


This event is generated when you select the LDAP Connection Reestablished option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Connection to user store replica reestablished 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Store Replica Name Data Description: Replica name 
SubTarget (Y): null 


Text1 (S): Schema Title: User Store Replica Host Data Description: IP Address of User Store replica 
server 


Text2 (T): null 
Text3 (F): null 
Value! (1): 0 
Group (G): 0 
Data Length (X): 0 
Data (D): null 


NIDS: Server Started (002e0014) 


This event is generated when you select the Server Started option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: Server started 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: Configuration Identifier Data Description: Configuration Object DN 
SubTarget (Y): null 


Text1 (S): Schema Title: Server Identifier Data Description: Unique server ID also used to create 
Liberty and SAML artifacts 


Text2 (T): null 
Text3 (F): null 
Value! (1): 0 
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Group (G): 0 
Data Length (X): 0 
Data (D): null 


30.17.21 NIDS: Server Stopped (002e0015) 


This event is generated when you select the Server Stopped option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: Server stopped 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: Configuration Identifier Data Description: Configuration object DN 
SubTarget (Y): null 


Text1 (S): Schema Title: Server Identifier Data Description: Unique server ID also used to create 
Liberty and SAML artifacts 


Text2 (T): null 
Text3 (F): null 
Value! (1): 0 
Group (G): 0 
Data Length (X): 0 
Data (D): null 


30.17.22 NIDS: Server Refreshed (002e0016) 


This event is generated when you select the Server Refreshed option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: Server Refreshed 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: Configuration Identifier Data Description: Configuration Object DN 
SubTarget (Y): null 


Text1 (S): Schema Title: Server Identifier Data Description: Unique server ID also used to create 
Liberty and SAML artifacts 


Text2 (T): null 
Text3 (F): null 
Value! (1): 0 
Group (G): 0 
Data Length (X): 0 
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Data (D): null 


NIDS: Intruder Lockout (002e0017) 


This event is generated when you select the Intruder Lockout Detected option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: NIDS: Intruder Lockout 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 
SubTarget (Y): null 


Text1 (S): Schema Title: Server Identifier Data Description: IP address of the User Store replica 
server 


Text2 (T): null 
Text3 (F): null 
Value1 (1): 0 
Group (G): 0 
Data Length (X): 0 
Data (D): null 


NIDS: Severe Component Log Entry (002e0018) 


This event is generated when you select the Component Log Severe Messages option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Severe Component Log Entry 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): Schema Title: Component Log Text Data Description: Server Error Text 
Text2 (T): null 

Text3 (F): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 
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30.17.25 NIDS: Warning Component Log Entry (002e0019) 


This event is generated when you select the Component Log Warning Messages option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Warning Component Log Entry 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): Schema Title: Component Log Text Data Description: Warning Error Text 
Text2 (T): null 

Text3 (F): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


30.17.26 NIDS: Failed to Broker an Authentication from Identity 
Provider to Service Provider as Identity Provider and 
Service Provider Are not in Same Group (002E001A) 


This event is generated when you select the Brokering Across Groups Denied option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Failed to broker an authentication from identity provider to service provider as 
identity provider and service provider are not in same group 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 

SubTarget (Y): null 

Text1 (S): Schema Title: Identity Provider IdentifierDescription : Identity Provider ID 

Text2 (T): Schema Title: Service Provider IdentifierDescription: Service Provider ID 

Text3 (F): null 

Value1 (1): 0 

Group (G): 0 

Data Length (X): Schema Title: Target URL Length Description: Byte length of the target URL 
Data (D): Schema Title: Target URL Description: Target URL 
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NIDS: Failed to Broker an Authentication from Identity 
Provider to Service Provider Because a Policy Evaluated to 
Deny (002E001B) 


This event is generated when you select the Brokering Rule Evaluated to Deny option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: Failed to broker an authentication from identity provider to service provider 
because a policy evaluated to deny 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 

SubTarget (Y): Schema Title: Broker Group Name Description: Name of the Brokering Group 

Text1 (S): Schema Title: Identity Provider IdentifierDescription: Identity Provider ID 

Text2 (T): Schema Title: Service Provider IdentifierDescription: Service Provider ID 

Text3 (F): Schema Title: Broker Policy Description: Name of the Broker Policy that evaluated to deny 
Value1 (1): 0 

Group (G): 0 

Data Length (X): Schema Title: Target URL Length Description: Byte length of the target URL 

Data (D): Schema Title: Target URL Description: Target URL 


NIDS: Brokered an Authentication from Identity Provider to 
Service Provider (002E001C) 


This event is generated when you select the Brokering Handled option under Audit Logging on the 
Logging page of an Identity Server configuration. 


Description: NIDS: Brokered an authentication from identity provider to service provider 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 

SubTarget (Y): Schema Title: Broker Group Name Description: Name of the Brokering Group 
Text1 (S): Schema Title: Identity Provider Identifier Description: Identity Provider ID 

Text2 (T): Schema Title: Service Provider Identifier Description: Service Provider ID 

Text3 (F): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): Schema Title: Target URL Length Description: Byte length of the target URL 
Data (D): Schema Title: Target URL Description: Target URL 
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30.17.29 NIDS: OAuth2 Authorization code issued (002e0028) 


This event is generated when you select the OAuth & OpenID Token Issued option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 Authorization code issued 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Issued At Data 

Data Description: Token issued time stamp in Millisecond 
Text2 (T): Schema Title: Issued To Data 

Description: Client Name 

Text3 (F): Schema Title: Validity Data 


Description: From: Time in Milliseconds - To: Time in Milliseconds 


30.17.30 NIDS: OAuth2 token issued (002e0029) 


This event is generated when you select the OAuth & OpenID Token Issued option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 token issued 

Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): Schema Title: Grant Type 

Data Description: Oauth grant type 

Text1 (S): Schema Title: Issued At 

Data Description: Token issued time stamp in Milliseconds 
Text2 (T): Schema Title: Issued To 

Data Description: Client Name plus session id seperated by '-'. 
Text3 (F): Schema Title: Validity 


Data Description: From: Time in Milliseconds - To: Time in Milliseconds 
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30.17.31 


30.17.32 


30.17.33 


NIDS: OAuth2 Authorization code issue failed (002e0030) 


This event is generated when you select the OAuth & OpenID Token Issue Failed option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 Authorization code issue failed 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Failed At 

Data Description: Code issued failed time stamp in Milliseconds 
Text2 (T): Schema Title: Reason 

Data Description: Reason for failure 


Text3 (F): null 


NIDS: OpenID token issued (002e0031) 


This event is generated when you select the OAuth & OpenID Token Issue option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OpenID token issued 

Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1(S): Schema Title: Issued At 

Data Description: ID Token issued time stamp in Millisecond 
Text2(T): Schema Title: Issued To 

Data Description: Client Name s 

Text3(F): Schema Title: Expires 


Data Description: Expires in second 


NIDS: OAuth2 refresh token issued (002e0032) 


This event is generated when you select the OAuth & OpenID Token Issue option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 refresh token issued 
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30.17.34 


30.17.35 


Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Issued At 

Data Description: Token issued time stamp in Millisecond 
Text2 (T): Schema Title: Issued To 

Data Description: Client Name 

Text3 (F): Schema Title: Validity 


Data Description: From: Time in Milliseconds - To: Time in Milliseconds 


NIDS: OAuth2 token issue failed (002e0033) 


This event is generated when you select the OAuth & OpenID Token Issue Failed option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 token issue failed 

Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): Schema Title: Grant Type 

Data Description: Oauth grant type 

Text1 (S): Schema Title: Failed At 

Data Description: Token issue failed time stamp in Milliseconds 
Text2 (T): Schema Title: Issued To 

Data Description: Client Name 

Text3 (F): Schema Title: Reason 


Data Description: Reason for failure 


NIDS: OpenID token issue failed (002e0034) 


This event is generated when you select the OAuth & OpenID Token Issue Failed option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OpenID token issue failed 
Originator (B): Schema Title: Originator 
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Data Description: JCC Device ID (AMDEVICEID#device_id:) 

Target (U): Schema Title: User Identifier Data Description: Authentication User Name 
SubTarget (Y): null 

Text1 (S): Schema Title: Failed At 

Data Description: Token issue failed time stamp in Milliseconds 

Text2 (T): Schema Title: Issued To 

Data Description: Client Name 

Text31 (F): Schema Title: Reason 


Data Description: Reason for failure 


NIDS: OAuth2 refresh token issue failed (002e0035) 


This event is generated when you select the OAuth & OpenID Token Issue Failed option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 refresh token issue failed 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Failed At 

Data Description: Token issue failed time stamp in Milliseconds 
Text2 (T): Schema Title: Issued To 

Data Description: Client Name 

Text31 (F): Schema Title: Reason 


Data Description: Reason for failure 


NIDS: OAuth2 client has been registered successfully 
(002e0036) 


This event is generated when you select the OAuth Client Applications option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 client has been registered successfully 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 


Data Description: Authentication User Name 
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30.17.38 


30.17.39 


SubTarget (Y): null 

Text1 (S): Schema Title: Registered At 

Data Description: Client registered time stamp in Milliseconds 

Text2 (T): Schema Title: Client Name Data Description: Client Name 
Text31 (F): Schema Title: Client ID 


Data Description: Client ID 


NIDS: OAuth2 client has been modified successfully 
(002e0037) 


This event is generated when you select the OAuth Client Applications option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 client has been modified successfully 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Modified At 

Data Description: Client modify time stamp in Milliseconds 

Text2 (T): Schema Title: Client Name 

Data Description: Client Name 


Text31 (F): Schema Title: Client ID Description: Client ID 


NIDS: OAuth2 client has been deleted successfully 
(002e0038) 


This event is generated when you select the OAuth Client Applications option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 client has been deleted successfully 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Removed At 


Data Description: Client deleted time stamp in Milliseconds 
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30.17.41 


30.17.42 


Text2 (T): Schema Title: Client Name 
Data Description: Client Name 


Text31 (F): Schema Title: Client ID Description: Client ID 


NIDS: OAuth2 user has provided consent (002e0039) 


This event is generated when you select the OAuth Consent Provided option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 user has provided consent 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Provided At 

Data Description: Consent provided time stamp in Milliseconds 
Text2 (T): null 

Text31 (F): null 


NIDS: OAuth2 user has revoked consent (002e0040) 


This event is generated when you select the OAuth Consent Revoked option under Audit Logging on 
the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 user has revoked consent 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Revoked At 

Data Description: Consent revoked time stamp in Milliseconds 
Text2 (T): null 

Text31 (F): null 


NIDS: OAuth2 token validation success (002e0041) 


This event is generated when you select the OAuth & OpenID Token Validation Success option 
under Audit Logging on the Logging page of an Identity Server configuration. 
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Description: NIDS: OAuth2 token validation success 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Validated At 

Data Description: Validated time stamp in Milliseconds 
Text2 (T): null 

Text31 (F): Schema Title: Expires 


Data Description: Expires in seconds 


30.17.43 NIDS: OAuth2 token validation failed (002e0042) 


This event is generated when you select the OAuth & OpenID Token Validation Failed option under 
Audit Logging on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 token validation failed 
Originator (B): Schema Title: Originator 

Data Description: JCC Device ID (AMDEVICEID#device_id:) 
Target (U): null 

SubTarget (Y): null 

Text1 (S): Schema Title: Validated At 

Data Description: Validated time stamp in Milliseconds 
Text2 (T): null 

Text31 (F): Schema Title: Reason 

Data Description: Validation failure reason 

Data (D): Schema Title: Client IP Address 


Description: IP Address of the host from which the token received 


30.17.44 NIDS: OAuth2 client registration failed (002e0043) 


This event is generated when you select the OAuth Client Applications option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: NIDS: OAuth2 client registration failed 
Originator (B): Schema Title: Originator 
Data Description: JCC Device ID (AMDEVICEID#device_id:) 
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30.17.46 


Target (U): Schema Title: User Identifier 

Data Description: Authentication User Name 

SubTarget (Y): null 

Text1 (S): Schema Title: Failed At 

Data Description: Client registration failed time stamp in Milliseconds 
Text2 (T): Schema Title: Client Name 

Data Description: Client Name 

Text31 (F): Schema Title: Reason 


Data Description: Reason for failure 


NIDS: Roles PEP Configured (002e0300) 


This event is generated for Identity Server roles. 
Description: NIDS: Roles PEP Configured 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): null 

Text2 (T): null 

Text3 (F): null 

Value1 (1): 0 

Group (G): 0 

Data Length (X): Schema Title: Policy Enforcement List Length Data Description: Byte length of PEL 


Data (D): Schema Title: Policy Enforcement List Data Description: Policy Enforcement List (PEL) 
data 


NIDS: Risk-Based Authentication Action for User 
(002e0045) 


This event is generated when you select the Risk-based Pre-authentication Succeeded option under 
Audit Logging on the Logging page of an Identity Server configuration. 


Description: Pre-Risk-Based additional authentication executed successfully for user. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Name Identifier Description: Risk type (preauth or 
postauth) 
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30.17.47 


30.17.48 


Text1 (S): Schema Title: RiskScore Description: Risk score(number) plus IDP session id seperated 
by '-'. 


Text2 (T): Schema Title: RiskLevel Description: Risk category defined by risk score value plus user 
agent seperated by '-'. 


Text3 (F): Schema Title: Authentication class Description: Authentication class name executed as 
part of risk based authentication. 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


NIDS: Risk-Based Authentication Action for User 
(002e0046) 


This event is generated when you select the Risk-based Pre-authentication Failed option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: Pre-Risk-Based authentication failed for user. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Name Identifier Description: Risk type (preauth or 
postauth) 


Text1 (S): Schema Title: RiskScore Description: Risk score(number) plus IDP session id seperated 
by '-'. 


Text2 (T): Schema Title: RiskLevel Description: Risk category defined by risk score value plus user 
agent seperated by '-'. 


Text3 (F): Schema Title: Authentication class Description: Authentication class name executed as 
part of risk based authentication. 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


NIDS: Risk-Based Authentication Action for User 
(002e0047) 


This event is generated when you select the Risk-based Pre-authentication Action Invoked option 
under Audit Logging on the Logging page of an Identity Server configuration. 


Description: Pre-Risk-Based authentication action for user. 
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Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Name Identifier Description: Risk type (preauth or 
postauth) 


Text1 (S): Schema Title: RiskScore Description: Risk score(number) plus IDP session id seperated 
by '-'. 


Text2 (T): Schema Title: RiskLevel Description: Risk category defined by risk score value plus user 
agent plus cluster id of IDP all seperated by '-'. 


Text3 (F): Schema Title: Action taken Description: Risk category defined action taken as part of risk 
based authentication. 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


NIDS: Token was Issued to Web Service (002E001F) 


This event is generated when you select the Token Issued To WebService option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: When a token is issued to a web service (WS-Trust) 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN. 
SubTarget (Y): Schema Title: Token type Data Description: Type of token issued. 


Text1 (S): Schema Title: Identity Provider Identifier Data Description: Identity provider identifier 
providing token. 


Text2 (T): Schema Title: Authentication Method Data Description: Authentication method name. 
Text3 (F): Schema Title: Target Name Data Description: Target name of service provider. 
Data Length (X): 0 


Data (D): Schema Title: Target URL Data Description: Target url of service provider. 


NIDS: Issued a Federation Assertion (002E0102) 


This event is generated when you select the Federation Token Sent option under Audit Logging on 
the Logging page of an Identity Server configuration. 


Description: When a federation token is issued. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 
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30.17.51 


30.17.52 


Target (U): Schema Title: User Identifier Data Description: User DN. 

SubTarget (Y): Schema Title: Authentication Identifier Data Description: IDP Session ID. 

Text1 (S): Schema Title: Provider Name Data Description: Name of the provider 

Text2 (T): Schema Title: Provider Identifier Data Description: Identity provider identifier. 

Text3 (F): Schema Title: User Agent-Cluster ID Data Description: User agent and IDP cluster ID. 
Data Length (X): 0 

Data (D): Schema Title: Client IP Address Data Description: Client IP address. 


NIDS: Received a Federation Assertion (002E0103) 


This event is generated when you select the Federation Token Received option under Audit Logging 
on the Logging page of an Identity Server configuration. 


Description: When a federation token is received. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN. 

SubTarget (Y): Schema Title: Authentication Identifier Data Description: IDP Session ID. 

Text1 (S): Schema Title: Provider Name Data Description: Name of the provider 

Text2 (T): Schema Title: Provider Identifier Data Description: Identity provider identifier. 

Text3 (F): Schema Title: User Agent-Cluster ID Data Description: User agent and IDP cluster ID. 
Data Length (X): 0 

Data (D): Schema Title: Client IP Address Data Description: Client IP address. 


Access Gateway: PEP Configured (002e0301) 


This event is generated when you enable auditing. 
Description: Access Gateway: policy enforcement point (PEP) configured 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): Schema Title: Event Identifier Data Description: Event Tracking Identifier 

Text2 (T): null 

Text3 (F): null 

Value! (1): Schema Title: Audit Enabled Data Description: 0 = No; 1 = Yes 

Group (G): 0 

Data Length (X): Schema Title: Policy Enforcement List Length Data Description: Byte length of PEL 
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Data (D): Schema Title: Policy Enforcement List Data Description: Policy Enforcement List (PEL) 
data 


30.17.53 Roles Assignment Policy Evaluation (002e0320) 


This event is generated when you enable auditing. 
Description: Roles assignment policy evaluation 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEI|D#device_id:) 


Target (U): null 
SubTarget (Y): null 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text2 (T): Schema Title: Assigned Roles Data Description: Assigned Role or error message 
Text3 (F): Schema Title: Policy Action Data Description: Policy Action FDN 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


30.17.54 Access Gateway: Authorization Policy Evaluation 
(002e0321) 


This event is generated when you enable auditing. 
Description: Access Gateway: Authorization policy evaluation 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): null 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text2 (T): Schema Title: Event Identifier Data Description: Event Tracking Identifier 
Text3 (F): Schema Title: Policy Action Data Description: Policy Action FDN 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 
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30.17.55 Access Gateway: Form Fill Policy Evaluation (002e0322) 


This event is generated when you enable auditing. 
Description: Access Gateway: Form Fill policy evaluation 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): null 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text2 (T): Schema Title: Event Identifier Data Description: Event Tracking Identifier 
Text3 (F): Schema Title: Policy Action Data Description: Policy Action FDN 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


30.17.56 Access Gateway: Identity Injection Policy Evaluation 
(002e0323) 


This event is generated when you enable auditing. 
Description: Access Gateway: Identity Injection policy evaluation 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): null 


Text1 (S): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text2 (T): Schema Title: Event Identifier Data Description: Event Tracking Identifier 
Text3 (F): Schema Title: Policy Action Data Description: Policy Action FDN 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 
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30.17.58 


Access Gateway: Access Denied (0x002e0505) 


This event is generated when you select the Access Denied option on the Audit page of an Access 
Gateway. 


Description: Access Gateway: Access Denied 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0505 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: Protected Resource Name Data Description: Configured Name of 
Protected Resource 


SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 


Value! (1): Schema Title: Source IP Address Data Description: User IP address (numeric format — 
host order) 


Group (G): 0 
Data Length (X): 0 
Data (D): null 


Access Gateway: URL Not Found (0x002e0508) 


This event is generated when you select the URL Not Found option on the Audit page of an Access 
Gateway. 


Description: Access Gateway: URL Not Found 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0508 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 
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Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 


Value! (1): Schema Title: Source IP Address Data Description: User IP address (numeric format — 
host order) 


Group (G): 0 
Data Length (X): 0 
Data (D): null 


30.17.59 Access Gateway: System Started (0x002e0509) 


This event is generated when you select the System Started option on the Audit page of an Access 
Gateway. 


Description: Access Gateway: System Started 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0509 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): null 
SubTarget (Y): null 
Text1 (S): null 
Text2 (T): null 
Text3 (F): null 
Value! (1): 0 
Group (G): 0 

Data Length (X): 0 
Data (D): null 


30.17.60 Access Gateway: System Shutdown (0x002e050a) 


This event is generated when you select the System Shutdown option on the Audit page of an 
Access Gateway. 


Description: Access Gateway: System Shutdown 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
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Event ID: 0x002e050a 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): null 
SubTarget (Y): null 
Text1 (S): null 
Text2 (T): null 
Text3 (F): null 
Value! (1): 0 
Group (G): 0 

Data Length (X): 0 
Data (D): null 


Access Gateway: Identity Injection Parameters 
(0x002e050c) 


This event is generated when you select the Identity Injection Parameters option on the Audit page 
of an Access Gateway. 


Description: Access Gateway: Identity Injection Parameters 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e050c 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 


Value! (1): Schema Title: Injection Location Data Description: 2710 — Auth Header 2720 — Custom 
Header 2730 — Query Parameters 


Group (G): 0 
Data Length (X): 0 
Data (D): null 
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30.17.62 Access Gateway: Identity Injection Failed (0x002e050d) 


This event is generated when you select the Identity Injection Failed option on the Audit page of an 
Access Gateway. 


Description: Access Gateway: Identity Injection Failed 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e050d 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 


Value! (1): Schema Title: Injection Location Data Description: 2710 — Auth Header 2720 — Custom 
Header 2730 — Query Parameters 


Group (G): 0 
Data Length (X): 0 
Data (D): null 


30.17.63 Access Gateway: Form Fill Authentication (0x002e050e) 


This event is generated when you select the Form Fill Success option on the Audit page of an 
Access Gateway. 


Description: Access Gateway: Form Fill Authentication 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e050e 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: Protected Resource Name Data Description: Configured name of 
protected resource 


SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 
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Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 
Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


Access Gateway: Form Fill Authentication Failed 
(0x002e050f) 


This event is generated when you select the Form Fill Failed option on the Audit page of an Access 
Gateway. 


Description: Access Gateway: Form Fill Authentication Failed 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e050f 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: Protected Resource Name Data Description: Configured name of 
protected resource 


SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 
Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


Access Gateway: URL Accessed (0x002e0512) 


This event is generated when you select the URL Accessed option on the Audit page of an Access 
Gateway. 


Description: Access Gateway: URL Accessed 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 
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In a query, this column is called EventID. 
Event ID: 0x002e0512 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 


Value! (1): Schema Title: Source IP Address Data Description: User IP address (numeric format — 
host order) 


Group (G): 0 
Data Length (X): 0 
Data (D): null 


Access Gateway: IP Access Attempted (0x002e0513) 


This event is generated when you select the IP Access Attempted option on the Audit page of an 
Access Gateway. 


Description: Access Gateway: IP Access Attempted 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0513 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 


Value! (1): Schema Title: Source IP Address Data Description: User IP address (numeric format — 
host order) 


Group (G): 0 
Data Length (X): 0 
Data (D): null 
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Access Gateway: Webserver Down (0x002e0515) 


This event is generated when you select the IP Access Attempted option on the Audit page of an 
Access Gateway. 


Description: Access Gateway: One of the Web servers is not reachable 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0515 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): WebServer hostname 
Text2 (T): null 

Text3 (F): null 

Value1 (1): WebServer IP Address 
Group (G): 0 

Data Length (X): 0 

Data (D): null 


Access Gateway: All WebServers for a Service is Down 
(0x002e0516) 


This event is generated when you select the IP Access Attempted option on the Audit page of an 
Access Gateway. 


Description: Access Gateway: All Web servers for a service are down 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0516 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): WebServer Hostname 
Text2 (T): null 

Text3 (F): null 
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Value! (1): WebServer IP address 
Group (G): 0 

Data Length (X): 0 

Data (D): null 


Access Gateway: Application Accessed (002E0514) 


This event is generated when you select the Application Accessed option on the Audit page of an 
Access Gateway. 


Description: Access Gateway: An application has been accessed with authentication in AG. 
Event ID: 0x002e0514 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: Protected Resource Name Data Description: Name of protected resource. 
SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Application Name Data Description: Application that has been accessed. 


Value! (1): Schema Title: Source IP Address Data Description: User IP address (numeric format — 
host order) 


Group (G): 0 
Data Length (X): 0 
Data (D): Schema Title: ESP Provider Id Data Description: ID of ESP. 


Access Gateway: Session Created (002E0525) 


This event is generated when you select the Session Created/Destroyed option on the Audit page of 
an Access Gateway. 


Description: Access Gateway: Session has been created in AG. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): null 
SubTarget (Y): Schema Title: Protected Resource URL Data Description: Protected Resource URL 
Text1 (S): Schema Title: User Identifier Data Description: User DN 


Text2 (T): Schema Title: Authentication Identifier Data Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text3 (F): Schema Title: Event Identifier Data Description: Event Tracking Identifier 


Troubleshooting 1331 


30.17.71 


30.17.72 


Value! (1): Schema Title: Source IP Address Data Description: User IP address (numeric format — 
host order) 


Value! (2): Schema Title: X-Forwarded-For Client IP Address Data Description: X-Forwarded-For 
header value for client IP 


Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Provider Id Data Description: Device ID of provider. 


Management Communication Channel: Health Change 
(0x002e0601) 


This event is generated when you select the Health Changes option on the Access Manager Auditing 
page. 


Description: Management Communication Channel: Health Change 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0601 


Originator (B): Schema Title: Originator Data Description: “devmanagement” 
(AMDEVICE|ID#devmanagement:) 


Target (U): null 
SubTarget (Y): null 


Text1 (S): Schema Title: Changed Device Data Description: IP address and device type of the 
changed device 


Text2 (T): Schema Title: Old State Data Description: Old State 
Text3 (F): Schema Title: New State Data Description: New State 
Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


Management Communication Channel: Device Imported 
(0x002e0602) 


This event is generated when you select the Server Imports option on the Access Manager Auditing 
page. 


Description: Management Communication Channel: Device Imported 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 
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30.17.73 


In a query, this column is called EventID. 
Event ID: 0x002e0602 


Originator (B): Schema Title: Originator Data Description: “devmanagement” 
(AMDEVICE|ID#devmanagement:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): Schema Title: Device Data Description: IP address and device type of the changed device 
Text2 (T): blank string 

Text3 (F): blank string 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 


Management Communication Channel: Device Deleted 
(0x002e0603) 


This event is generated when you select the Server Deletes option on the Access Manager Auditing 
page. 


Description: Management Communication Channel: Device Deleted 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0603 


Originator (B): Schema Title: Originator Data Description: “devmanagement” 
(AMDEVICE|ID#devmanagement:) 


Target (U): null 

SubTarget (Y): null 

Text1 (S): Schema Title: Device Data Description: IP address and device type of the changed device 
Text2 (T): Schema Title: Administrator Data Description: DN of the administrator deleting the device 
Text3 (F): blank string 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 

Data (D): null 
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30.17.74 Management Communication Channel: Device 
Configuration Changed (0x002e0604) 


This event is generated when you select the Configuration Changes option on the Access Manager 
Auditing page. 


Description: Management Communication Channel: Device Configuration Changed 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0604 


Originator (B): Schema Title: Originator Data Description: “devmanagement” 
(AMDEVICE|ID#devmanagement:) 


Target (U): null 
SubTarget (Y): null 
Text1 (S): Schema Title: Device Data Description: IP address and device type of the changed device 


Text2 (T): Schema Title: Administrator Data Description: DN of the administrator invoking the 
configuration change 


Text3 (F): blank string 
Value! (1): 0 

Group (G): 0 

Data Length (X): 0 
Data (D): null 


30.17.75 Management Communication Channel: Device Alert 
(0x002e0605) 


This event is generated when you enable auditing. 
Description: Management Communication Channel: Device Alert 


In the Event list (Auditing and Logging > Logging Server Options > [Name of Novell Audit Secure 
Logging Server] > Novell Access Manager > Events), this column is called Event Name. 


In a query, this column is called EventID. 
Event ID: 0x002e0605 


Originator (B): Schema Title: Originator Data Description: “devmanagement” 
(AMDEVICE|ID#devmanagement:) 


Target (U): null 
SubTarget (Y): null 
Text1 (S): Schema Title: Device Data Description: IP address of the device generating the alert 


Text2 (T): Schema Title: Alert Message Data Description: alert message string 
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Text3 (F): blank string 
Value! (1): 0 

Group (G): 0 

Data Length (X): 0 
Data (D): null 


30.17.76 Management Communication Channel: Statistics 
(002e0606) 


This event is generated when you select the Server Statistics option on the Access Manager Auditing 
page 


Description: Management Communication Channel: Statistics of IDP ESP and AG. 


Originator (B): Schema Title: Originator Data Description: “devmanagement” 
(AMDEVICE|ID#devmanagement:) 


Target (U): null 


SubTarget (Y): Schema Title: Device IP Address Data Description: IP address of devices like IDP or 
AG. 


Text1 (S): Schema Title: Device Data Description: Device type of the device 
Text2 (T): null 

Text3 (F): null 

Value! (1): 0 

Group (G): 0 

Data Length (X): 0 


Data (D): Schema Title: Statistics Data Description: Statistics data. 


30.17.77 Risk-Based Authentication Successful (002e0025) 


This event is generated when you select the Risk-Based Authentication Succeeded option under 
Audit Logging on the Logging page of an Identity Server configuration. 


Description: Risk-Based additional authentication executed successfully for user. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Identifier Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text1 (S): Schema Title: RiskScore Description: Risk score(number). 
Text2 (T): Schema Title: RiskLevel Description: Risk category defined by risk score value. 


Text3 (F): Schema Title: Additional authentication class Description: Additional Authentication class 
name executed as part of risk based authentication. 
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30.17.78 


30.17.79 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


Risk-Based Authentication Failed (002e0026) 


This event is generated when you select the Risk-Based Authentication Failed option under Audit 
Logging on the Logging page of an Identity Server configuration. 


Description: Risk-Based authentication failed for user. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICE|D#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Identifier Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text1 (S): Schema Title: RiskScore Description: Risk score(number). 
Text2 (T): Schema Title: RiskLevel Description: Risk category defined by risk score value. 


Text3 (F): Schema Title: Additional authentication class Description: Additional Authentication class 
name executed as part of risk based authentication. 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


Risk-Based Authentication for User (002e0027) 


This event is generated when you select the Risk-Based Authentication Action Invoked option under 
Audit Logging on the Logging page of an Identity Server configuration. 


Description: Risk-Based authentication action for user. 


Originator (B): Schema Title: Originator Data Description: JCC Device ID 
(AMDEVICEID#device_id:) 


Target (U): Schema Title: User Identifier Data Description: User DN 


SubTarget (Y): Schema Title: Authentication Identifier Description: IDP Session ID 
(AMAUTHID#auth_id:) 


Text1 (S): Schema Title: RiskScore Description: Risk score(number) plus IDP session id seperated 
by '-'. 


Text2 (T): Schema Title: RiskLevel Description: Risk category defined by risk score value plus user 
agent plus cluster id of IDP all seperated by '-'. 
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Text3 (F): Schema Title: Action taken Description: Risk category defined action taken as part of risk 
based authentication. 


Value! (1): 0 
Group (G): 0 
Data Length (X): 0 


Data (D): Schema Title: Client IP Address Description: IP Address of the host from which the 
authentication succeeded. 


30.17.80 Impersonation Sign in (002E0048) 


This event is generated during an Impersonation sign in. 
appName: Novell Access Manager 

timeStamp: Thu, 15 Sep 2016 17:18:58 -0600 
eventid: ID of the event 

SubTarget: Impersonator’s session ID 
stringValue1: Impersonatee’s userDN or username 
stringValue2: Impersonatee’s session ID 
stringValue3: Description of the event 
numericValue1: 0 

numericValue2: 0 

numericValue3: 0 

data: IP address in the base64 format 

description: null 

message: null 

component: nidp\\\\impersonation 

originator: JCC device ID 


target: Impersonator’s UserDN or username 


30.17.81 Impersonation: Impersonator Logs Out (002E0049) 


This event is generated when an Impersonator logs out from an Impersonation session. 
appName: Novell Access Manager 

timeStamp: Thu, 15 Sep 2016 17:18:58 -0600 

eventid: ID of the event 

SubTarget: Impersonator’s session ID 


stringValue1: Impersonatee’s userDN or username 
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30.17.82 


30.17.83 


stringValue2: Impersonatee’s session ID 
stringValue3: Description of the event 
numericValue1: 0 

numericValue2: 0 

numericValue3: 0 

data: IP address in the base64 format 
description: null 

message: null 

component: nidp\\\\impersonation 
originator: JCC device ID 


target: Impersonator’s UserDN or username 


Impersonation: Session Started (002E0050) 


This event is generated when an Impersonation session is started. 
appName: Novell Access Manager 

timeStamp: Thu, 15 Sep 2016 17:18:58 -0600 
eventid: ID of the event 

SubTarget: Impersonator’s session ID 
stringValue1: Impersonatee’s userDN or username 
stringValue2: Impersonatee’s session ID 
stringValue3: Description of the event 
numericValue1: 0 

numericValue2: 0 

numericValue3: 0 

data: IP address in the base64 format 

description: null 

message: null 

component: nidp\\\\impersonation 

originator: JCC device ID 


target: Impersonator’s UserDN or username 


Impersonation: Impersonatee Denies (002E0051) 


This event is generated when an Impersonatee denies an Impersonation session request. 


appName: Novell Access Manager 
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timeStamp: Thu, 15 Sep 2016 17:18:58 -0600 
eventid: ID of the event 

SubTarget: Impersonator’s session ID 
stringValue1: Impersonatee’s userDN or username 
stringValue2: Impersonatee’s session ID 
stringValue3: Description of the event 
numericValue1: 0 

numericValue2: 0 

numericValue3: 0 

data: IP address in the base64 format 
description: null 

message: null 

component: nidp\\\\impersonation 

originator: JCC device ID 


target: Impersonator’s UserDN or username 


30.17.84 Impersonation: Impersonatee Approves (002E0052) 


This event is generated when an Impersonatee approves an Impersonation session request. 
appName: Novell Access Manager 

timeStamp: Thu, 15 Sep 2016 17:18:58 -0600 
eventid: ID of the event 

SubTarget: Impersonator’s session ID 
stringValue1: Impersonatee’s userDN or username 
stringValue2: Impersonatee’s session ID 
stringValue3: Description of the event 
numericValue1: 0 

numericValue2: 0 

numericValue3: 0 

data: IP address in the base64 format 

description: null 

message: null 

component: nidp\\\\impersonation 


originator: JCC device ID 
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30.17.85 


30.17.86 


target: Impersonator’s UserDN or username 


Impersonation: Impersonator Cancels (002E0053) 


This event is generated when an Impersonator cancels an Impersonation session request. 
appName: Novell Access Manager 

timeStamp: Thu, 15 Sep 2016 17:18:58 -0600 
eventid: ID of the event 

SubTarget: Impersonator’s session ID 
stringValue1: Impersonatee’s userDN or username 
stringValue2: Impersonatee’s session ID 
stringValue3: Description of the event 
numericValue1: 0 

numericValue2: 0 

numericValue3: 0 

data: IP address in the base64 format 

description: null 

message: null 

component: nidp\\\\impersonation 

originator: JCC device ID 


target: Impersonator’s UserDN or username 


Impersonation: Authorization Policy Fails (002E0054) 


This event is generated when an Impersonation session authorization policy fails. 
appName: Novell Access Manager 

timeStamp: Thu, 15 Sep 2016 17:18:58 -0600 
eventid: ID of the event 

SubTarget: Impersonator’s session ID 
stringValue1: Impersonatee’s userDN or username 
stringValue2: Impersonatee’s session ID 
stringValue3: Description of the event 
numericValue1: 0 

numericValue2: 0 

numericValue3: 0 


data: IP address in the base64 format 
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description: null 

message: null 

component: nidp\\\\impersonation 
originator: JCC device ID 


target: Impersonator’s UserDN or username 


30.18 Event Codes 


Event codes for Access Manager consist of 4 fields that describe the type of code and the module 
that produced it: 
¢ Severity (1 digit) 


+ 1 = severe - Describes problems that needs to be resolved in order for the system to run 
correctly. 


+ 2 = error - Describes that a failure occurred, but the system is operational. 


+ 3 = warn - Describes a situation that may exist that the administrator should be aware of 
and may need to address. The system is currently running properly 


+ 4 = config - Describes configuration related information. 
+ 5= info - Describes events that occur. 
+ 6 = debug - Describes execution points within the software. 


¢ 9 = internal - Describes an error that is for internal use only. This error code will not be 
documented in any public documentation. 


+ Component issuing the error code (3 digits) 
¢ Sub-grouping for further classification within a component (2 digits) 
+ Event code (three digits) 


0 000 00 000 


Severity Component field Sub-grouping Event Code 


The following sections divide the event codes by component, then describe them: 


¢ Section 30.18.1, “Administration Console (009),” on page 1342 

¢ Section 30.18.2, “Identity Server (001),” on page 1378 

¢ Section 30.18.3, “Linux Access Gateway Appliance(045),” on page 1419 
¢ Section 30.18.4, “Access Gateway Service (046),” on page 1420 

¢ Section 30.18.5, “Server Communications (JCC) (007),” on page 1424 

¢ Section 30.18.6, “Policy Engine (008),” on page 1443 

¢ Section 30.18.7, “SOAP Policy Enforcement Point (011),” on page 1447 
¢ Section 30.18.8, “Backup and Restore (010),” on page 1452 

¢ Section 30.18.9, “Modular Authentication Class (012),” on page 1457 
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30.18.1 Administration Console (009) 


Component 009 


¢ Subgroup 01: Certificate Manager 


+ 


+ 


+ 


+ 


+ 


Subgroup 02: Application 
Subgroup 03: Platform 
Subgroup 04: Web UI 
Subgroup 05: Roma Application 
Subgroup 06: Policy 


Event Code Description 


100901001 


100901002 


100901003 


100901004 
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Application 


Error getting web manager. 


Error in initializing the dirCerts APIs. 


Error in init. 


Error in 
CertHandler.getMultipartParamValue. 


Remedy 


Cause: Administration Console was not 
installed correctly or has become corrupt. 


Action: Verify installation. 


Cause: Administration Console was not 
installed correctly or has become corrupt. 
Specifically, the PKI and/or certificate 
management jars may be missing or have 
mismatched versions. 


Action: Verify that the certmgr .jar file is 
contained in the /var/opt/novell/ 
tomcat4/webapps/roma/WEB-INF/lib 
directory and that PKI has been installed. 


Verify that the Java command line contains 
the following: 


-Djava.library.path=/opt/novell/1lib 
Verify that npki. jar is in the classpath. 


Cause: Administration Console was not 
installed correctly or has become corrupt. 


Action: Verify installation. 


Cause: Servlet error when retrieving data 
from a multipart form. 


Action: Submit log to Novell Support for 
analysis and resolution. 


Event Code Description 


100901008 


100901010 


100901011 


Could not remove certificate with the given 
alias from the keystore. 


Error In CertHandler.doGetSigningCertDN. 


Error in creating or configuring one or more 
of Identity Server Configuration cluster 
keystores. 


Remedy 


Cause: The keystore that contains the 
certificate might not exist or might have 
become corrupt. 


Action: View the configuration store and find 
the keystore object and check that the 
certificate is no longer in the key list. If it is 
there, manually remove it. 


Also, find the keystore on the file system of 
the device and remove the key manually, 
using the Java keytool program for JKS 
keystores. 


Cause: Unable to retrieve the DN of the 
signing cert. 


Cause: The signing cert does not exist. 
Cause: The signing keystore does not exist. 


Action: View Identity Server Configuration's 
Signing keystore to verify that it exists and 
contains a certificate. If the signing keystore 
does not exist, there has been an error during 
the import of an Identity Server or during the 
creation of an Identity Server Configuration. 


Check to make sure that there are no corrupt 
Identity Server configurations. If the signing 
keystore does exist, add or replace a 
certificate. 


Cause: Test certificates might have been 
accidentally deleted from the file system. 


Cause: Error communicating with Identity 
Server(s) while pushing down the test 
certificates. 


Action: Use the exception stack trace to 
discover a more detailed description of the 
error. Go to the Certificates tab and verify that 
the test-connector, test-signing, test- 
encryption, test-provider, test-consumer 
certificates have not been deleted. 


Also verify they still exist on the file system. 
Go to the Trusted Roots tab and verify that 
the configCA trusted root has not been 
deleted and that it exists in the configuration 
store. These test certificates are pushed 
down to each Identity Server during the 
creation of an Identity Server configuration. 


You can delete Identity Server configuration 
and create a new one and add Identity 
Servers back into the new configuration. 
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Event Code Description 


100901012 


100901013 


700901014 


700901015 


700901016 


700901017 


700901020 


700901021 


100901023 
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keystore already exists. 


Error in init (using reflection to calla 
method has failed in init). 


Cannot add non-existent key to keystore. 


Cannot add key to non-existent keystore. 


Could not add key to keystore because the 
alias was too long. 


Could not add key to keystore because the 
maximum number of keys has been 
reached. 


Cannot remove non-existent key from 
keystore. 


Cannot remove key from non-existent 
keystore. 


CertHandler.doGetCertFromServer: Could 
not connect to server IP and port. 


Remedy 


Cause: You are trying to create a keystore 
that already exists on the device. 


Action: Use the existing keystore. 


Cause: The java class is unable to locate 
another java class through reflection. 


Action: Submit log to Novell Support for 
analysis and resolution. 


Cause: The certificate you are trying to add 
to a keystore does not exist. 


Action: Specify a valid key to be added to 
the keystore. 


Cause: The keystore does not exist. 


Action: Specify a valid keystore or create the 
keystore. 


Cause: Some platforms and keystore 
formats only support a limited number of 
characters in the alias name. 


Action: Use a shorter alias. 


Cause: Many keystores allow only one key to 
be contained in it because the keystore has a 
specific purpose in . 


Action: Remove unused keys from the 
keystore and try again. 


Cause: The key no longer exists in . 


Action: View the configuration store and find 
the keystore object and manually remove the 
key from the key list. 


Cause: The keystore does not exist. 
Action: Specify a valid keystore. 


Cause: The server IP or DNS name and port 
combination is not reachable. 


Action: Verify that the IP address or DNS 
name exists and that the port is correct. You 
can try connecting to it with a web browser or 
other utility. 


Event Code Description Remedy 


100901024  CertHandler.doGetCertFromServer: Cause: The server IP or DNS name and port 


certificate was not obtained from server IP_ combination had no certificate to be 
and port. presented. 


Action: Verify that the IP address or DNS 
name exists and that the port is correct. 
Verify that the server you are attempting to 
import the certificate from has a certificate. 
You can try connecting to it with a web 
browser or other utility. 


100901025 Error in handleException. Cause: The exception reported has no 
details associated with it. 


Action: Scroll up in the log to see if there is a 
stack trace immediately above this error, 
determine what steps you had taken to create 
this error condition, and submit the log and 
steps to Novell Support. 


100901026 The node keystore does not exist. Cannot Cause: The grouping of Identity Servers 
add cluster keys to a non-existent (Identity Server Configuration) or Access 
keystore. Gateways is trying to locate a keystore on 

one of Identity Server or Access Gateway 
devices but the keystore cannot be found. 


Action: Verify that Identity Servers and 
Access Gateway devices had no errors 
during import to Administration Console. Try 
to re-import the devices. 


100901027 Error in Cause: The cluster keystore representation 
CertHandler.getNIDPDeviceKeystoreNam object was not found. 


e (The name of the device's keystore was , 
not found). Cause: The cluster keystore representation 


did not have a device type specified. 


Action: Delete and recreate Identity Server 
Configuration or Access Gateway Group that 
is causing the problem and then re-add the 
members. 


100901028 Error in CertHandler.isTomcatCert (Unable Cause: The certificate representation has 
to determine if the specified certificate is missing or invalid attributes. 


the one being used by Tomcat). 
Action: Delete this certificate and re-import 


it. 


100901030 Error in Cause: The cluster object was not found in 
CertHandler.getNodeKeystoreNames (The the configuration store, the type of the cluster 
cluster object was not found in the could not be determined, or the cluster server 
configuration store, or the cluster server list was empty. 


list was empty). 
Action: No action needed unless your 


devices are unable to communicate. If you 
are having problems with communication, 
delete and recreate Identity Server 
configuration or Access Gateway cluster that 
is causing the problem. 
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Event Code Description 


100901031 


100901032 


100901033 


100901034 


100901035 


700901036 


700901037 


700901038 


1346 Troubleshooting 


Error in 
CertHandler.getClusterDisplayName (The 
cluster object was not found in the 
configuration store). 


The device does not exist but the 
certificate is in a keystore assigned to that 
device. 


The device does not exist but the keystore 
is assigned to that device. 


Unable to retrieve the primary member of 
the group. 


Unable to remove the node keystore 
setting off Access Gateway group device. 


Unable to set the Update Servers status. 


Unable to remove all keys from keystore. 


Unable to reinitialize keystore contents for 
a particular device in a group or 
configuration. 


Remedy 


Action: Delete and recreate Identity Server 
configuration or Access Gateway cluster that 
is causing the problem and then re-add the 
members. 


Cause: It's possible the device is ina 
partially-imported state. 


Action: Delete the keystore, if possible, and 
re-import the device. 


Cause: It's possible the device is ina 
partially-imported state. 


Action: Delete the keystore, if possible, and 
re-import the device. 


Cause: The group is corrupt. 


Action: Delete the group, re-create it, and re- 
add the members. 


Cause: Could not locate the keystore object 
in the configuration store. 


Action: No action required. 
Cause: Communication error. 


Action: Manually restart or update the 
device. 


Cause: The keystore does not exist. 


Cause: There is a corrupt key in the 
keystore. 


Action: Manually remove each certificate 
from the keystore. 


Cause: One of the device keystores does not 
exist. 


Action: Re-create the keystore or delete and 
recreate the group or configuration and then 
re-add the devices to it. 


Cause: There was an error either removing 
all certificates from a keystore. 


Action: Manually remove all certificates from 
the keystore and then remove and re-add 
that device to the group/configuration. 


Cause: There was an error adding the test 
certificates to a keystore. 


Action: Verify that the test certificates exist 
(see error 1.009.01.011 for more detail). 
Manually add the test certificates to the 
keystore. Or remove the device from the 
group/configuration and re-add it. 


Event Code Description 


700901039 


700901040 


100901041 


100901042 


100901043 


100902001 


100902002 


100902003 


Unable to assess whether the keystore 
contains a tomcat connector certificate. 


Error adding a key to keystore during the 
renew certificate process. 


Unable to extract the public key from a key 
during the auto-import public certificate 
process. 


Unable to set up the initial keys for the 
cluster. 


The source keystore does not exist. 
Cannot push keys from a non-existent 
keystore. 


Application 


Error - Exception thrown in eventOccurred 
of 
vcdn.application.sc.alert.AlertEventListene 
r 


Error - Exception thrown in eventOccurred 
of 
vcdn.application.sc.alert.AlertEventListene 
r. 


Error - Exception thrown in logAlert of 
vcdn.application.sc.alert.AlertLogger. 


Remedy 


Cause: The cluster keystore representation 
does not exist or is corrupt. 


Cause: Unable to locate the devices in the 
group/configuration. 


Action: Delete and recreate the group/ 
configuration and re-add the devices to it. 


Cause: The original certlficate information 
could not be located. 


Action: Manually create a new certificate 
and place it into all the keystores which 
previously held the certificate being renewed. 


Cause: The source keystore does not exist. 
Action: Select a valid keystore. 


Cause: The specified source key does not 
exist. 


Action: Verify that the key you have 
specified to export the public certificate from 
exists. 


Cause: When trying to locate the cluster 
keystores so that their contents can be 
initialized, one or more of those keystore 
representations could not be found. 


Action: Delete and recreate Identity Server 
configuration or Access Gateway cluster. 


Cause: The source keystore does not exist. 


Action: Usually the source keystore is a 
cluster keystore representation. Try deleting 
and recreating Identity Server configuration 
or Access Gateway cluster to ensure those 
cluster keystore representations get created. 


Cause: Cannot post alert to internal 
subsystem. 


Action: Non-fatal error. No action required. 


Cause: Cannot post alert to internal 
subsystem. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Problem occurred update Identity 
Server Alert count. 


Action: Non-fatal error. May be a symptom 
of a more serious condition. Submit the 
app_sc. 0. log file for resolution. 
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1348 


Event Code Description 


100902004 Error - Exception thrown in the execute 
method of 
vcdn.application.sc.alert.CertUpdateWork. 


100902005 Error - (The specified device) has not been 
imported. Failed to start device. 


100902006 Error importing device (with the specified 
ID). 


100902007 Error - Import failed. Retrying. 


100902008 Error auto importing. Retry. 


100902009 Error - Could not create subcontext: 
cn=(The specified Context) 


Troubleshooting 


Remedy 


Cause: Could not update or read the list of 
trusted server certificates. 


Action: Be sure the /var/opt/novell/ 
novlwww/devman.cacerts file exists, is a 
valid Java keystore, and is not corrupted. To 
check its status, enter the following 
command: 


/opt/novell/java/bin/keytool -v -list 
-keystore devman.cacerts 


Otherwise, be sure the config store is running 
and functioning properly. 


Cause: Identity Server was not properly 
imported. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import. 
functionality works for any server type.) 
Otherwise, submit the app_sc . ©. log file for 
resolution. 


Cause: The Server was not properly 
imported. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import. 
functionality works for any server type.) If this 
fails, reinstall the server component. 


Cause: Unable to communicate with the 
Server being imported. 


Action: Be sure the firewall is allowing port 
1443 traffic. Otherwise allow the system to 
retry for several minutes. If the server does 
not appear in the Server List, click Repair 
Import to resolve the issue. Otherwise, 
submit the app_sc.@.1og file for resolution. 


Cause: Unable to communicate with the 
Server being imported. 


Action: Be sure the firewall is allowing port 
1443 traffic. Otherwise allow the system to 
retry for several minutes. If the server does 
not appear in the Server List, click Repair 
Import. to resolve the issue. Otherwise, 
submit the app_sc.0.10g file for resolution. 


Cause: Error creating Server object in config 
store during import. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import 
functionality works for any server type.) 
Otherwise, submit the app_sc.0.1log file for 
resolution. 


Event Code Description Remedy 


100902010 Error - (The given ESP) does not exist! Cause: There was a error during 
Administration Console installation. 


Action: Reinstall Administration Console. 


100902011 Error - Exception reading (the given ESP) Cause: The file required during the import 
process could not be read. 


Action: Be sure the indicated file can be read 
by the noviwww user. 


100902012 Error - Could not import LDIF. Cause: The error occurred while creating the 
configuration for the Embedded Service 
Provider. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import 
functionality works for any server type.) 
Otherwise, submit the app_sc . ©. log file for 
resolution. 


100902013 Error - Could not find (the specified DN) Cause: Error connecting to the config store 
while importing the Embedded Service 
Provider. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import 
functionality works for any server type.) 
Otherwise, submit the app_sc . ©. log file for 
resolution. You might need to restart 
Administration Console. 


100902014 Error - ESP Configuration was not found, Cause: Could not find the configuration for 
so auto-import failed. the imported Embedded Service Provider. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import 
functionality works for any server type.) 
Otherwise, submit the app_sc . ©. log file for 
resolution. 


100902015 Error - Exception thrown in importDevice of Cause: Error during import of server 
vedn.application.sc.alert.RegisterComman component. 


d. 
Action: Go to Access Gateway Server List 


and click Repair Import. (The repair import 
functionality works for any server type.) 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


100902016 Error - ImportThread null member vars. Cause: Internal error occurred during import. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import 
functionality works for any server type.) 
Otherwise, submit the app_sc . ©. log file for 
resolution. 
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Event Code 


100902017 


100902018 


100902019 


100902020 


100902021 


100902022 


100902023 


100902024 
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Description 


Error - Could not connect to eDir for certs. 


Error during execution. 


Error - Could not get (the given number of) 
bytes of payload data. 


Error - VException thrown while executing 
command in 
vedn.application.sc.alert.AlertCommandHa 
ndler. 


Error - VCDNException thrown in 
performConfiguration of 
vcdn.application.sc.config.AGApplyWork 


Error - VCDNException thrown in 
responseReceived method of 
vcdn.application.sc.config.AGApplyWork 


Error - VCDNException thrown in 
performConfiguration method of 
vcdn.application.sc.config.AGConfigWork 


Error - VCDNException thrown in 
responseReceived method of 
vcdn.application.sc.config.AGConfigWork 


Remedy 


Cause: Either the primary Administration 
Console is down (if this is a secondary 
console), or the config store is down. 


Action: Be sure the config store is operating 
properly and that port 554 is not blocked by a 
firewall. 


Cause: Error executing an external program 
during import process. 


Action: Go to Access Gateway Server List 
and click Repair Import. (The repair import 
functionality works for any server type.) 
Otherwise, submit the app_sc . ©. log file for 
resolution. 


Cause: An error occurred while trying to read 
data for a command. 


Action: Ensure the server component is 
operating properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Problem executing a command from 
a server component. 


Action: Ensure the server component is 
operating properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Problem occurred while sending 
configuration to Access Gateway server. 


Action: Ensure the server component is 
operating properly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred in processing the 
response from an Access Gateway server. 


Action: Ensure the server component is 
operating properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while sending 
configuration to Access Gateway server. 


Action: Ensure the server component is 
operating properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred in processing the 
response from an Access Gateway server. 


Action: Ensure the server component is 
operating properly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Event Code 


100902025 


100902031 


100902032 


100902033 


100902034 


100902035 


100902036 


100902037 


100902038 


Description 


Error - Exception thrown in 
processAGResponse method of 
vcdn.application.sc.config.AGConfigWork 


Error - SchedulerException thrown in 
configureDeviceNow method of 
vedn.application.sc.config. ConfigManager 


Error - Exception thrown in the execute 
method of 
vcdn.application.sc.config. ConfigWork 


Error setting LDAP attribute in 
performPendingActions of 
vcdn.application.sc.config.ConfigWork 


Error invoking method in 
performPendingActions of 
vedn.application.sc.config.ConfigWork 


Error executing pending action (name) in 
performPendingActions of 
vcdn.application.sc.config. ConfigWork 


Error - Exception thrown in getConfigXML 
of vcdn.application.sc.config.ConfigWork 


Error - VException thrown in savelnDB 
method of 
vcdn.application.sc.config.ConfigWork 


Error - VException thrown in 
configFinished method of 
vcdn.application.sc.config. DeviceConfigAp 
plyWork 


Remedy 


Cause: Error occurred in processing the 
response from an Access Gateway server. 


Action: Ensure the server component is 
operating properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while scheduling an 
immediate apply of the current configuration. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while performing 
pending actions. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Pending actions could not be 
completed because of a problem 
communicating with the config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Problem occurred while invoking a 
method during a pending action. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Problem occurred while displaying a 
pending dialog message. 


Action: This is a non-fatal error. If the 
problem persists, submit the app_sc.@.1log 
file for resolution. 


Cause: Error occurred while retrieving XML 
data from the config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while saving the 
applied configuration in the config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while sending the 
Audit event for a changed configuration. 


Action: Ensure the Audit server and the 
config store are functioning properly. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 
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Event Code 


100902039 


100902040 


100902041 


100902042 


100902043 


100902044 


100902045 


100902046 


100902047 


1352 Troubleshooting 


Description 


Error - VException thrown in 
configFinished method of 
vcdn.application.sc.config.DeviceConfigW 
ork 


Error - Exception thrown in 
processConfigDiff method of 
vcdn.application.sc.config.DeviceGroupCo 
nfigWork 


Error - Exception thrown in 
memberConfigFinished method of 
vcdn.application.sc.config.DeviceGroupCo 
nfigWork 


Error - Exception thrown in 
removePendingFromFailedList method of 
vcdn.application.sc.config.DeviceGroupCo 
nfigWork 


Error - SchedulerException thrown in 
scheduleMultiDeviceWorks method of 
vedn.application.sc.config.DeviceGroupCo 
nfigWork 


Error - Exception thrown in the execute 
method of 
vcdn.application.sc.config.DeviceGroupCo 
nfigWork 


Error - VException thrown in performWork 
method of 
vcdn.application.sc.config.MultiDeviceCon 
figWork 


Error - Exception thrown in performWork 
method of 
vcdn.application.sc.config.MultiDeviceCon 
figWork 


Error - SchedulerException thrown in 
getDeviceGroupConfigWork method of 
vcdn.application.sc.config.MultiDeviceCon 
figWork 


Remedy 


Cause: Error occurred while sending the 
Audit event for a changed configuration. 


Action: Ensure the Audit server and the 
config store are functioning properly. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while parsing the XML 
for a group configuration. 


Action: Error occurred while sending the 
Audit event for a changed configuration. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while processing a 
group member configuration apply response. 


Action: Ensure the server component is 
functioning properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while re-applying a 
server configuration. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while scheduling a 
group configuration. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while scheduling a 
group configuration. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while applying 
configuration to a group member. 


Action: Ensure the server component is 
functioning properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while applying 
configuration to a group member. 


Action: Ensure the server component is 
functioning properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while trying to get the 
scheduled configuration. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Event Code Description 


100902048 


100902049 


100902050 


100902051 


100902055 


100902056 


100902057 


100902058 


100902059 


Error - VException thrown in 
configFinished method of 
vcdn.application.sc.config.MultiDeviceCon 
figWork 


Error - VCDNException thrown in the 
execute method of 
vcdn.application.sc.command.AGComman 
dWork 


Error - Exception thrown in the 
sendCommand method of 
vedn.application.sc.command.AGComman 
dWork 


Error - Exception thrown in the 
processAGResponse method of 
vedn.application.sc.command.AGComman 
dWork 


Error - IOException thrown in the 
addCommand method of 
vcdn.application.sc.command.CertComma 
nd 


Error - IOException thrown in the 
generateCmd method of 
vedn.application.sc.command.CertComma 
nd 


Error - IOException thrown in the 
setCertChainData method of 
vedn.application.sc.command.CertComma 
nd 


Error - VCDNException thrown in the 
execute method of 
vcdn.application.sc.command.IDPComma 
ndWork 


Error - VCDNException thrown in the 
sendCommand method of 
vcdn.application.sc.command.|DPComma 
ndWork 


Remedy 


Cause: Error occurred while importing status 
from a group member. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while sending a 
command to an Access Gateway server. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while sending a 
command to an Access Gateway server. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing a 
command response from an Access Gateway 
server. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error generating certificate 
command. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error generating certificate 
command. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error generating chained certificate 
command. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while sending a 
command to an Identity Server ESP server. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while sending a 
command to an Identity Server or ESP 
server. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code Description 


100902060 


010090261 


100902062 


100902063 


100902064 


100902065 


300902069 


100902070 


1354 Troubleshooting 


Error - NamingException thrown in the 
updateNIDPCommandStatus method of 
vcdn.application.sc.command.|IDPComma 
ndWork 


Error - VException thrown in the 
updateNIDPCommandStatus method of 
vcdn.application.sc.command.|DPComma 
ndWork 


Error - Exception thrown in the 
processIDPResponse method of 
vcdn.application.sc.command.|DPComma 
ndWork 


Error - VCDNException thrown in the 
execute method of 
vedn.application.sc.command.JCCComma 
ndWork 


Error - Exception thrown in the 
sendCommand method of 
vedn.application.sc.command.JCCComma 
ndWork 


Error - Exception thrown in the 
processResponse method of 
vcdn.application.sc.command.JCCComma 
ndWork 


Exception changing factory LocalAddress. 


Error - ConverterException thrown in the 
getCurrentDeviceXML method of 
vcdn.application.sc.core.AGDevice 


Remedy 


Cause: Error occurred while processing a 
command response from an Identity Server 
or ESP. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing a 
command response from an Identity Server 
or ESP. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing a 
command response from an Identity Server 
or ESP. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while executing a 
server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while sending a 
server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing a 
response from a server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while changing 
factory XML during configuration import. 


Action: Submit the app_sc.0.1log file for 
resolution. 


Cause: Error occurred during translation of 
NetWare Access Gateway configuration. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Event Code 


100902071 


100902072 


100902073 


100902074 


100902075 


100902076 


100902077 


100902078 


100902079 


Description 


Error - NamingException thrown in the 
importDevice method of 
vedn.application.sc.core. AGDevice 


Error - VException thrown in the 
importDevice method of 
vedn.application.sc.core. AGDevice 


Error - Exception thrown in the 
importDevice method of 
vcdn.application.sc.core. AGDevice 


Error - NamingException thrown in the 
vcdn.application.sc.core.AuditManager 
constructor. 


Error - JOOMException thrown in the 
processDocument method of 
vcdn.application.sc.core.AuditManager 


Error - Exception thrown in the 
processDocument method of 
vedn.application.sc.core.AuditManager 


Error - Exception thrown in the 
setDefaultServer method of 
vedn.application.sc.core.AuditManager 


Error - VException thrown in the 
writeConfig method of 
vcdn.application.sc.core.AuditManager 


Error - NamingException thrown in the 
writeConfig method of 
vcdn.application.sc.core.AuditManager 


Remedy 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1log file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1log file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1log file for resolution. 


Cause: Audit XML data could not be parsed. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Invalid data format. 


Action: Attempt the operation again. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code 


100902080 


100902081 


100902082 


100902083 


100902084 


100902085 


100902086 


300902087 


100902088 


100902089 
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Description 


Error - Exception thrown in the writeConfig 
method of 
vedn.application.sc.core.AuditManager 


Error - SException thrown in the 
getIDPConfigObject method of 
vcdn.application.sc.core.AuditManager 


Error - NamingException thrown in the 
getIDPConfigObject method of 
vcdn.application.sc.core.AuditManager 


Error - Exception thrown in the 
getIDPConfigObject method of 
vcdn.application.sc.core.AuditManager 


Error - NullPointerException thrown in the 
logEvent method of 
vedn.application.sc.core.AuditManager 


Error - Exception thrown in the 
creatElement method of 
vedn.application.sc.core.DeviceConfig 


Error - Exception thrown in the 
setLastModified method of 
vedn.application.sc.core.DeviceConfig 


Warning - Exception thrown in the 
getLastScheduledWorkID method of 
vcdn.application.sc.core.DeviceGroupMan 
ager 


Error - Could not get version from device. 
Make sure it is running properly. 


Error - NamingException thrown in the 
importDevice method of 
vcdn.application.sc.core.DeviceManager 


Remedy 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Config store could not be accessed 
or an internal error occurred. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error logging Novell Audit event. 


Action: Ensure the Novell Audit server is 
functioning properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal XML error. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Internal XML error. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: The last executed command status 
ID could not be read. 


Action: Non-fatal error. 


Cause: Could not get version from device. 


Action: Make sure the server component is 
running properly, then click Repair Import to 
resolve the issue. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error importing device. 


Action: Make sure the server component is 
running properly, then click Repair Import to 
resolve the issue. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Event Code Description 


100902090 


100902091 


100902092 


100902093 


100902094 


100902095 


100902096 


100902097 


100902098 


Error - VException thrown in the 
importDevice method of 
vcdn.application.sc.core.DeviceManager 


Error - InvocationTargetException thrown 
in the importDevice method of 
vcdn.application.sc.core.DeviceManager 


Error - Exception thrown in the 
importDevice method of 
vcdn.application.sc.core.DeviceManager 


Error - Could not find esp cfg SCC to 
remove in cluster container. 


Error deleting the trusted IDP entry for 
ESP. 


Error - NamingException thrown in the 
setHealthCheck method of 
vcdn.application.sc.core.DeviceManager 


Error - Could not find the DN specified. 


Error - Exception thrown in the 
deleteDevice method of 
vcdn.application.sc.core.DeviceManager 


Error - Exception thrown in the 
setHealthCheck method of 
vcdn.application.sc.core.DeviceManager 


Remedy 


Cause: Error importing device. 


Action: Make sure the server component is 
running properly, then click Repair Import to 
resolve the issue. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error importing device. 


Action: Make sure the server component is 
running properly, then click Repair Import to 
resolve the issue. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error importing device. 


Action: Make sure the server component is 
running properly, then click Repair Import to 
resolve the issue. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error deleting improperly imported 
server. 


Action: Non-fatal error. 
Cause: Error accessing config store. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error saving health status in config 
store. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error saving health status in config 
store. 


Action: Ensure the server component 
imported correctly and the config store is 
functioning properly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while deleting the 
server objects. 


Action: Ensure the config store is functioning 
properly. Otherwise, submit the 
app_sc.0.1log file for resolution. 


Cause: Error updating the version following 
an upgrade of a server component. 


Action: Allow the operation to try again. 
Otherwise, submit the app_sc . ©. log file for 
resolution. 
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Event Code Description 


300902099 


300902100 


300902101 


100902102 


100902103 


100902104 
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Warning - Exception thrown in the 
getLastScheduledWorkID method of 
vcdn.application.sc.core.DeviceManager 


Device is not imported. 


Identity configuration not found for device. 


Error - Exception thrown in the 
createCertEntry method of 
vcdn.application.sc.core.KeyManager 


Error - Exception thrown in the 
deleteCertEntry method of 
vedn.application.sc.core.KeyManager 


Error - Exception thrown in the 
modifyCertEntryXml method of 
vcdn.application.sc.core.KeyManager 


Remedy 


Cause: The last executed command status 
ID could not be read. 


Action: Non-fatal error. 


Cause: Server component is sending health 
to Administration console that does not 
recognize the server. 


Action: Click Repair Import to resolve the 
issue. Otherwise, submit the app_sc.0.log 
file for resolution. 


Cause: Identity server configuration not 
found in config store. 


Action: Non-fatal error. 


Cause: The config store is not reachable or 
the user does not have rights to modify the 
config store 


Action: Verify the config store is up and that 
the user has rights to create objects in the 
following container: 


ou=KeyContainer, ou=Partition, ou=Parti 
tionsContainer, ou=VCDN_root, ou=access 
ManagerContainer, o=novell 


Cause: The config store is not reachable or 
the user does not have rights to modify the 
config store 


Action: Verify the config store is up and that 
the user has rights to delete objects in the 
following container: 


ou=KeyContainer, ou=Partition, ou=Parti 
tionsContainer, ou=VCDN_root, ou=access 
ManagerContainer, o=novell 


Cause: The config store is not reachable or 
the user does not have rights to modify the 
config store 


Action: Verify the config store is up and that 
the user has rights to modify objects in the 
following container: 


ou=KeyContainer, ou=Partition, ou=Parti 
tionsContainer, ou=VCDN_root, ou=access 
ManagerContainer, o=novell 


Event Code Description Remedy 


100902105 Error - Exception thrown in the Cause: The config store is not reachable or 
createKeyStoreEntry method of the user does not have rights to modify the 
vcdn.application.sc.core.KeyManager config store 


Action: Verify the config store is up and that 
the user has rights to create objects in the 
following container: 


ou=KeyContainer, ou=Partition, ou=Parti 
tionsContainer, ou=VCDN_root, ou=access 
ManagerContainer, o=novell 


100902106 Error - Exception thrown in the Cause: The config store is not reachable or 
deleteKeyStoreEntry method of the user does not have rights to modify the 
vedn.application.sc.core.KeyManager config store 


Action: Verify the config store is up and that 
the user has rights to delete objects in the 
following container: 


ou=KeyContainer, ou=Partition, ou=Parti 
tionsContainer, ou=VCDN_root, ou=access 
ManagerContainer, o=novell 


100902107 Error - Exception thrown in the Cause: The config store is not reachable or 
modifyKeyStoreEntryXml method of the user does not have rights to modify the 
vcdn.application.sc.core.KeyManager config store 


Action: Verify the config store is up and that 
the user has rights to modify objects in the 
following container: 


ou=KeyContainer, ou=Partition, ou=Parti 
tionsContainer, ou=VCDN_root, ou=access 
ManagerContainer, o=novell 


100902108 Error - Exception thrown in the Cause: Error creating an element in the 
createElement method of specified XML document. 


vcdn.application.sc.core.PolicyConfig 
Action: Submit the app_sc.0.1og file for 


resolution. 
100902109 Error - Exception thrown in the Cause: Error setting an attribute value on 
setLastModified method of modified elements. 


vcdn.application.sc.core.PolicyConfig 
Action: Submit the app_sc.0.1og file for 


resolution. 


100902113 Error - Exception thrown in the sendData Cause: Error communicating with 


method of component. 
vcdn.application.sc.core.work.DeleteDevic , l 
eWork Action: Ensure the server component is 


functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


100902114 Error - Exception thrown in the execute Cause: Error occurred while executing a 
method of server command. 
vcdn.application.sc.core.work.ReimportDe , , 
viceWork Action: Ensure the server component is 


functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code 


100902115 


100902116 


100902117 


100902118 


100902119 


100902120 


100903001 


100903002 
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Description 


Error - Exception thrown in the getHealth 
method of 
vedn.application.sc.health.HealthCheck 


Error - Inner Exception thrown in the 
execute method of 
vcdn.application.sc.health.HealthCheck 


Error - Outer Exception thrown in the 
execute method of 
vcdn.application.sc.health.HealthCheck 


Error - VException thrown in the 
eventOccurred method of 
vcdn.application.sc.health.HealthEventList 
ener 


Error getting Health Module or Service 


Error - Exception thrown in the execute 
method of 
vcdn.application.sc.health.HealthUpdateW 
ork 


Platform 


Error - Unable to find a trusted client 
certificate. 


Error building delayed response. 


Remedy 


Cause: Error occurred while executing a 
server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while executing a 
server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while executing a 
server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while receiving/ 
logging a health event. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while executing a 
server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while executing a 
server command. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: There was a problem during the 
import of the device. 


Action: Consult the documentation to re- 
import the device into Administration 
Console. 


Cause: Error occurred while processing a 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Event Code 


100903003 


100903004 


100903005 


100903006 


100903007 


100903008 


100903009 


100903010 


100903011 


Description 


Error setting return code in 
HttpServiletResponse. 


Error - DelayedResponseListener thread 
failed to start. 


Error in the ResponseHandler thread of 
the DelayedResponseListener. 


Error creating XML Element in 
ResponseBuilder. 


Error waiting on mutex in 
RequestDispatcher. 


Error notifying mutex in 
RequestDispatcher. 


Error receiving in Sendinternal of 
VConnection. 


Error getting response code in 
VConnection. 


Error in stopScheduledResponses of 
VConnection. 


Remedy 


Cause: Error occurred while processing a 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing a 
delayed response. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing a 
response. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while editing XML. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting 
responses. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while receiving a 
response. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while receiving an 
internal response. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting the 
code. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while attempting to 
stop scheduled responses. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code 


100903012 


100903013 


100903014 


100903015 


100904001 


100904002 


100904003 


100904004 


100904005 


1362 Troubleshooting 


Description 


Error in ConsumeData of VConnection. 


Error in sendData of VConnection. 


Error in getHeaders of VConnection. 


Error in receive of VConnection. 


Web UI 


Error reading manager data in UlManager. 


Error during auto authentication in 
WebApplicaitonFilter. 


Error - Exception thrown in doFilter of 
WebApplicationFilter. 


Error - Exception thrown in logout of 
WebApplicationFilter. 


Error - VException thrown in getUserInfo of 
WebManager. 


Remedy 


Cause: Error occurred while reading data. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while sending data. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting headers. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while receiving a 
response. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while reading data. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while authenticating. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error getting panel data. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while logging out. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while getting user 
information. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Event Code Description 


100904006 


100904007 


100904008 


100904009 


100904010 


100904011 


100904012 


100904013 


100904014 


Error - Exception thrown in getDevicelnfo 
of WebManager. 


Error - Exception thrown in getPolicylnfo of 
WebManager. 


Error - Exception thrown in 
getTypeSpecificationInfo of WebManager. 


Error - Exception thrown in 
getDeviceConfig of WebManager. 


Error - Exception thrown in getPolicyConfig 
of WebManager. 


Error - Exception thrown in 
getTypeSpecificationConfig of 
WebManager. 


Error - Exception thrown in 
parameterMapToString of WebManager. 


Error while logging out user {0}. 


Error - Exception thrown in 
getSelectionCriteria of WebPanel. 


Remedy 


Cause: Error occurred while getting device 
information. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting policy 
information. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting policy 
type specification information. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting device 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting device 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting policy 
type specification configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while getting 
parameter information. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while logging out NDS 
user object. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting selection 
criteria. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code Description 


100904015 


100904016 


100904017 


100904018 


100904019 


100904020 


100904021 


100904022 


100904023 


1364 Troubleshooting 


Error - Exception thrown in 
getPanelVersion of WebPanel. 


Error - Group Config failed. 


Error - Schedule Group Config failed. 


Error - Update XML and Device Config 
failed. 


Error - Unlock Config failed. 


Error - Exception thrown in 
do_cancelPendingConfig of 
ConfigWorkDispatcher. 


Error - Exception thrown in 
do_cancelPendingConfig of 
ConfigWorkDispatcher. 


Error - Exception thrown in 
do_reapplyPendingConfig of 
ConfigWorkDispatcher. 


Error - Exception thrown in 
do_deviceConfig of 
ConfigWorkDispatcher. 


Remedy 


Cause: Error occurred while getting panel 
version. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while applying group 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while scheduling 
group configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while updating 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while unlocking the 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while canceling a 
pending configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while canceling a 
pending configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while reapplying a 
pending configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while applying 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Event Code 


100904024 


200904025 


100904026 


100904027 


100904028 


100904029 


100904030 


100904031 


Description 


Error - Exception thrown in 
do_scheduleDeviceConfig of 
ConfigWorkDispatcher. 


Error - XML VALIDATION FAILED. 
PLEASE CHECK APP_SC LOG. 


Error applying settings in 
ConfigXmlUpdateDispatcher. 


Error - Exception thrown in do_save of 
ConfigXmlUpdateDispatcher. 


Error - Exception thrown in do_cancel of 
ConfigXmlUpdateDispatcher. 


Error - Exception thrown in 
do_refreshConfig of 
ConfigXmlUpdateDispatcher. 


Error - Exception thrown in 
setLastModParams of 
ConfigXmlUpdateDispatcher. 


Error - IOException thrown in 
getXPathMap of 
ConfigXmlUpdateDispatcher. 


Remedy 


Cause: Error occurred while scheduling 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: XML created by GUI does not match 
the XML schema and fails validation. 


Action: Cancel the changes that were made 
and try again. In any case, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while applying 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while saving 
configuration. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while canceling 
configuration changes. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while refreshing 
configuration manager panel. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while setting an XML 
attribute. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while xpath mapping 
on the current panel. 


Action: Ensure the server component is 
functioning correctly. Cancel changes on the 
current panel, return, and try again. 
Otherwise, submit the app_sc . ©. log file for 
resolution. 
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Event Code 


100904032 


100904033 


100904034 


100904035 


100904036 


100904037 


100904038 


100904039 
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Description 


Error decoding: {0}. 


Error - Exception thrown in 
processRequest of ExceptionDispatcher. 


Error - Exception thrown in the service 
method of ServletDispatcher. 


Error - Exception thrown in 
ServletDispatcher. 


Error - Exception thrown in 
processRequest of 
DeviceCommandHandler. 


Error - VException thrown in 
setNIDPCommandState of 
DeviceCommandHandler. 


Error - NamingException thrown in 
setNIDPCommandsState of 
DeviceCommandHandler. 


Error - Could not find signing keystore for 


{0}. 


Remedy 


Cause: Error occurred while xpath mapping 
on the current panel. 


Action: Ensure the server component is 
functioning correctly. Cancel changes on the 
current panel, return, and try again. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while processing 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while inserting 
dispatchers. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while accessing data 
store. 


Action: Ensure the data store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while accessing data 
store. 


Action: Ensure the data store is functioning 
correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: An error occurred during the import 
of the device. 


Action: Consult the documentation and re- 
import the device into Administration 
Console. 


Event Code Description 


100904040 


100904041 


100904042 


100904043 


100904044 


100904045 


100904046 


Error - Could not find encryption keystore 
for {0}. 


Error - Could not find connector keystore 
for {0}. 


Error - Could not find trust keystore for {0}. 


Error - Could not find OCSP trust keystore 
for {0}. 


Error - No keys were assigned to keystore: 


{0}. 


Error - Exception thrown in 
processRequest of 
UpgradeDeviceGroupHandler. 


Error - Exception thrown in 
processRequest of 
UpgradeDeviceHandler. 


Remedy 


Cause: An error occurred during the import 
of the device. 


Action: Consult the documentation and re- 
import the device into Administration 
Console. 


Cause: An error occurred during the import 
of the device. 


Action: Consult the documentation and re- 
import the device into Administration 
Console. 


Cause: An error occurred during the import 
of the device. 


Action: Consult the documentation and re- 
import the device into Administration 
Console. 


Cause: An error occurred during the import 
of the device. 


Action: Consult the documentation and re- 
import the device into Administration 
Console. 


Cause: The keystore does not have any 
certificates in it. This may or may not be a 
bad condition. For instance, the OCSP trust 
store can be empty and that should not cause 
a problem. The signing, encryption, 
connector, provider, and consumer keystores 
should have one certificate in them. If it is 
empty, either the device import failed or the 
user manually removed the certificate from 
the keystore. 


Action: Check the keystore using the UI. If 
the keystore shows that it has a certificate, 
then the device import probably failed. 
Consult the documentation and re-import the 
device and also try deleting and re-creating 
the NIDP configuration. Also, try replacing 
the certificate in the keystore through the UI. 


Cause: Error occurred while processing 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code Description 


100904047 


100905001 


100905002 


100905003 


100905004 


100905005 


100905006 


100905007 


100905008 


1368 Troubleshooting 


Error - Exception thrown in getUpgradelnfo 
of UpgradeDeviceHandler. 


Application Handlers 


Error during repair import. 


Error - Failed to remove server. 


Error setting device groups. 


Error setting device admin. 


Error - Exception thrown while importing 
appliance. 


Error getting health info. 


Error canceling appliance creation. 


Error creating new CDN. 


Remedy 


Cause: Error occurred while getting update 
information. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while attempting to 
repair import. 


Action: Delete the server from the list and 
reinstall. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while attempting to 
remove server. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while attempting to 
mark a server as a member of a group. 


Action: Delete the server from the group and 
retry or delete the group and recreate. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while attempting to 
give an Administrator access to a server. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while importing a 
server. 


Action: Delete the server from the list and 
reinstall. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while getting health 
information for a server. 


Action: Ensure the server component and 
the config store are functioning correctly. 
Otherwise, submit the app_sc . ©. log file for 
resolution. 


Cause: Internal error. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Cause: Internal error. 


Action: Submit the app_sc.0.1og file for 
resolution. 


Event Code Description Remedy 


100905009 Error removing CDN. Cause: Internal error. 
Action: Submit the app_sc.0.1og file for 
resolution. 

100905010 Error creating new Admin. Cause: Internal error. 


Action: Submit the app_sc.0.1og file for 


resolution. 
100905011 Error while changing the cached device Cause: Internal error while processing 
port. request. 


Action: Ensure the Management IP Address 
is correct or edit as needed. Otherwise, 
submit the app_sc.0.1og file for resolution. 


100905012 Error while changing the cached device Cause: Internal error while processing 
password. request. 


Action: Ensure the Management Password 
is correct or edit as needed. Otherwise, 
submit the app_sc.@.1og file for resolution. 


100905013 Error - Exception thrown while processing Cause: Internal error while processing 
request in EditApplianceHandler request. 


Action: Ensure all values on the Server 
Details Edit page are correct and edit as 
needed. Otherwise, submit the 
app_sc.0.1og file for resolution. 


100905014 Error - Exception thrown while modifying | Cause: Error occurred while processing a 
device handler in EditDeviceHandler. request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


100905015 Error - Exception thrown while changing Cause: Error occurred while processing a 
password in EditDeviceHandler. request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


200905016 Error - Exception thrown while editing CDN Cause: Internal error. 


in EditPublisherHandler. 
Action: Ensure the config store is functioning 


correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


200905017 Error - Exception thrown while updating Cause: Internal error. 


CDN in EditPublisherHandler. 
Action: Ensure the config store is functioning 


correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code Description 


200905018 


200905019 


200905020 


200905021 


100905022 


200905023 


200905024 


200905025 


100905026 


100905027 
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Error - Failed to update the device groups 
for this user. 


Error - Failed to update the devices for this 
user. 


Error - Failed to update the cdns for this 
user. 


Error - Failed to update user data. 


Error processing client certs in 
GenericPipeHandler. 


Error accessing XML data item in generic 
pipe: {0} 


Error parsing XML data item in generic 
pipe: {0} 


Error processing XML data item in generic 
pipe: {0} 


Error - Exception thrown in 
processRequest of GenericPipeHandler: 


{0} 


Error occurred while creating group {0} : 


{1}. 


Remedy 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error while processing 
request. 


Action: Ensure the server component is 
functioning correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly or delete the group and recreate it. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Event Code Description 


100905028 


100905029 


100905030 


100905031 


100905032 


100905033 


100905034 


100905035 


100905036 


Error getting device manager in 
doGroupRemove of GroupCreateHandler. 


Error occurred while removing group {0}: 


{1}. 


Error occurred while getting device 
manager in doGroupAlertStatus of 
GroupCreateHandler. 


Error occurred while setting alert status for 
group {0}: {1}. 


Error occurred while updating group {0}: 


{1}. 


Error occurred while removing devices 
from group {0} : {1}. 


Error - Naming Exception thrown in 
removeDeviceFromCluster of 
GroupCreateHandler. 


Error - Exception thrown in 
removeDeviceFromCluster of 
GroupCreateHandler. 


Error - Exception thrown in 
removeDeviceFromCluster of 
GroupCreateHandler. 


Remedy 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly or delete the group again. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly or delete the group again. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Unable to get alert status for the 
group. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Unable to set alert status for the 
group. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Unable to make updates to the 
group. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Unable to remove servers from the 
group. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Unable to remove servers from the 
cluster. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while removing 
servers from the cluster. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while removing 
servers from the cluster. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1log file for resolution. 
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Event Code Description 


100905037 


100905038 


100905039 


100905040 


100905041 


100905042 


100905043 


100905044 


100905045 
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Error occurred while adding devices to 
group {0}: {1}. 


Error - Naming Exception thrown in 
addDeviceToCluster of 
GroupCreateHandler. 


Error - Exception thrown in 
addDeviceToCluster of 
GroupCreateHandler. 


Error - Exception thrown in 
addDeviceToCluster of 
GroupCreateHandler. 


Error occurred while adding devices to 
group {0}: {1}. 


Error - VCDNException thrown in 
processRequest of SyncHandler. 


Error - Exception thrown in 
processRequest of SyncHandler. 


Error - Exception thrown in 
modifySystemSync of SyncHandler. 


Error - WSException thrown in 
isAssignedUser of GroupCreateBean. 


Remedy 


Cause: Error occurred while adding servers 
to the group. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while adding servers 
to the cluster. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while adding servers 
to the cluster. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while adding servers 
to the cluster. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while adding servers 
to the cluster. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Event Code 


100905046 


100905047 


100905048 


100905049 


100905050 


100905051 


100905052 


100905053 


100905054 


100905055 


Description 


Error - WSException thrown in 


isAssignedDevice of GroupCreateBean. 


Error - WSException thrown in 


getApplianceByUrl of GroupCreateBean. 


Error - WSException thrown in 
generateMembershipList of 
GroupCreateBean. 


Error - WSException thrown in 
getAppGroupByName of 
GroupCreateBean. 


Error - WSException thrown in 
getDescForThisGroup of 
GroupCreateBean. 


Error - Exception thrown in 
getDescForThisGroup of 
GroupCreateBean. 


Error - WSException thrown in 


getLastModifiedDate of GroupCreateBean. 


Error - Get appliance groups failed in 


GroupCreateBean. 


Error - WSException thrown in 


hasAMembershipIn of GroupCreateBean. 


Error - Get appliances failed in 
GroupCreateBean. 


Remedy 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly or delete group and recreate it. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly or delete group and recreate it. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly or delete group and recreate it. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 
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Event Code 


100905056 


100905057 


100905058 


100905059 


100905060 


100905061 


100905062 


100905063 


100905064 


100905065 
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Description 


Error - Get admins failed in 
GroupCreateBean. 


Error - WSException thrown in 
getPerDeviceProperties of 
GroupCreateBean. 


Error - WSException thrown in 
getPerUserProperties of 
GroupCreateBean. 


Error - WSException thrown in 
getDeviceGroupProperties of 
GroupCreateBean. 


Error - NamingException thrown in 
setDeviceClusterConfig of 
GroupCreateBean. 


Error - Exception thrown in 
setDeviceClusterConfig of 
GroupCreateBean. 


Error - VException thrown in 
clusterServers of GroupCreateBean. 


Error - Exception thrown in clusterServers 
of GroupCreateBean. 


Error - VException thrown in getAdminList 
of GroupCreateBean. 


Error - Exception thrown in callRestartESP 
of SPConfigHandler. 


Remedy 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Internal error. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while restarting 
Embedded Service Provider. 


Action: Ensure the server component and 
ESP are functioning correctly or restart ESP 
again. Otherwise, submit the app_sc.@.log 
file for resolution. 


Event Code Description 


100905066 


100905067 


100905068 


100905069 


100905070 


100905071 


100905072 


100905073 


Error restarting {0}. 


Error - Could not lookup {0}. 


{0}. 


Error - Exception thrown in 


createTrustedIDP of SPConfigHandler. 


Error getting the esp trusted IDP. 


espTrustAccessDN not set. 


Error deleting trusted IDP config. 


Error - VCDNException thrown in 
processRequest of ScheduleHandler. 


Remedy 


Cause: Error occurred while restarting 
Embedded Service Provider. 


Action: Ensure the server component and 
ESP are functioning correctly or restart ESP 
again. Otherwise, submit the app_sc.@.log 
file for resolution. 


Cause: Error occurred while looking up DN in 
config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while accessing 
config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while accessing 
config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while accessing 
config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1log file for resolution. 


Cause: Error occurred while accessing 
config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Cause: Error occurred while accessing 
config store. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing 
request. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 
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Event Code Description 


100905074 


100905075 


100905076 


100905077 


100905078 


100905079 


100905080 


100905081 
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Error - Exception thrown in 
processRequest of ScheduleHandler. 


Error - Exception thrown in setEnable of 
ScheduleHandler. 


Error - Exception thrown while removing 
scheduled work in ScheduleHandler. 


Error - Exception thrown while releasing 
config lock in ScheduleHandler. 


Error - Exception thrown in modify method 
of ScheduleHandler. 


Error - Exception thrown in executeNow 
method of ScheduleHandler. 


Error - ParamNotFoundException thrown 
in createSchedule method of 
ScheduleHandler. 


Error - Cannot forward the request to 
return page. Nothing can be done. 


Remedy 


Cause: Error occurred while processing 
request. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing 
request. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while processing 
request. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while unlocking 
configuration. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while modifying 
scheduled work. 


Action: Ensure the config store is functioning 
correctly. Otherwise, submit the 
app_sc.0.1og file for resolution. 


Cause: Error occurred while scheduling 
work. 


Action: Ensure the config store and server 
component are functioning correctly. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Error occurred while scheduling 
work. 


Action: Ensure the config store and server 
component are functioning correctly. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: Internal error. 


Action: Ensure server component is 
functioning correctly and attempt to navigate 
to desired panels. Otherwise, submit the 
app_sc. 0. log file for resolution. 


Event Code Description 


100905082 


100905083 


1009 06000 


1009 06001 


1009 06002 


5009 06000 


5009 06001 


Error - Exception thrown in create method 
of ScheduleHandler. 


Config store Error 


Policy 


Cannot set update status for NULL policy 
extension. 


Cannot retrieve policy collection info object 
for the extension. 


Cannot retrieve device info object for a 
device 


Attempting to update policy status on 
devices because the policy extension 
changed. 


Setting update policy status for device. 


Remedy 


Cause: Error occurred while scheduling 
work. 


Action: Ensure the config store and server 
component are functioning correctly. 
Otherwise, submit the app_sc.0.1og file for 
resolution. 


Cause: The connection to the config store is 
experiencing problems. 


Action: To diagnose time synchronization 
issues with multiple Administration Consoles, 
run the following command on the primary 
server command-line: 


/opt/novell/eDirectory/bin/ndsrepair 
-T 


This will check the overall time 
synchronization status. If the time is not in 
sync, then you might want to consider 
configuring NTP on each server. 


Cause: The composite ID of the extension 
specified cannot be resolved to an extension 
ID. 


Action: On the device that is not receiving an 
Update status, make a configuration change 
to force the Update link to become active. 


Cause: The extension ID specified cannot be 
found in the configuration store. 


Action: If you see a problem with your 
extensions, note this error in the log and call 
support. 


Cause: When trying to set the Update status 
on devices which use an extension, the 
device info was unable to be located in the 
configuration store. 


Action: On the device that is not receiving an 
Update status, make a configuration change 
to force the Update link to become active. 


Cause: Informational message. 


Action: No action necessary. 


Cause: Informational message. 


Action: No action necessary. 
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30.18.2 Identity Server (001) 


Component 001 


¢ Subgroup 01: End user events 


¢ Subgroup 02: Web Service Framework (WSF) 
+ Subgroup 03: Web Service Consumer (WSC) 


¢ Subgroup 04: User Authentication 


Event Code Message 
100100001 
100100002 


100101001 No binding available or set for 
profile. 


100101043 IDP is unable to load ESP 
metadata. 
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Remedy 


Type: SEVERE:NIDP:INITIALIZE:001 
Type: SEVERE:NIDP:INITIALIZE:002 
Type: SEVERE:NIDP:USERMSG:001 


Cause: An action using Liberty or SAML protocols could 
not be completed because the server and trusted 
provider are not compatibly configured to interact to 
complete the action. 


Action: Set the desired protocol profiles in the 
administration tool to match those supported at the 
trusted provider. 


Type: SEVERE:NIDP:USERMSG:043 


Cause: The IDP cannot connect to the metadata URL 
for the ESP. The IDP may not be able to resolve the 
domain name for the ESP or if HTTPS is being used, 
the IDP may not trust the SSL certificate for the ESP. 
The ESP might also not be running. 


Action: Make sure that certificates for ESP are 
imported and trusted into IDP configuration. Check the 
metadata URL for the ESP and make sure the metadata 
can be retrieved from a browser: http://<DNS_name>/ 
nesp/idff/metadata 


If you are seeing this error after changing the IP address 
of Access Gateway, restart Tomcat on Identity Server. 


Cause: The IDP needs to have access to the internet to 
resolve and reach the CRL and OCSP URLs for ESP 
certificate validation. 


Action: Make sure the internet access is enabled, else 
the IDP will not trust the ESP certificate even if it has the 
signing and intermediary certificates. 


Event Code 


100101044 


100101045 


100102001 


100102002 


100102003 


100102004 


Message 


ESP is unable to load IDP 
metadata 


An error happened while the 
request was being sent to the 
correct cluster member for 
processing. 


Incomplete web service 
configuration. 


Invalid web service 
configuration. 


Unable to instantiate the web 
service provider authority 
class. This class will be 
com.novell.nidp.liberty.wsf.co 
nfig.authority.|dap. WSF Config 
AuthorityLdap. 


Unable to load web services. 


Remedy 


Type: SEVERE:NIDP:USERMSG:044 


Cause: The ESP cannot connect to the metadata URL 
for the IDP. The ESP may not be able to resolve the 
domain name for the IDP or if HTTPS is being used, the 
ESP may not trust the SSL certificate for the IDP. The 
IDP may also not be running 


Action: Make sure the IDP is running and that all 
certificates are imported and trusted. Check the 
metadata URL for the IDP and make sure the metadata 
can be retrieved from a browser: http://<DNS_name>/ 
nidp/idff/metadata A common cause is the base URL on 
the IDP is set incorrectly. 


For additional help, see Section 30.3.2, 
“Troubleshooting 100101043 and 100101044 Liberty 
Metadata Load Errors,” on page 1196. 


Type: SEVERE:NIDP:USERMSG:045 
Cause: The target cluster member may be unavailable. 


Action: Ensure that all cluster devices are operating 
correctly. 


Type: SEVERE:NIDP:WSF:001 


Cause: The web Service instance type (attribute 
nidsWsfServicelnstanceType on the nidsWsfService 
object) is not available in the service definition. 


Action: Delete the associated web service definition 
and recreate it. 


Type: SEVERE:NIDP:WSF:002 


Cause: The web service configuration XML (attribute 
nidsConfigXML on the nidsWsfService object) has 
invalid XML. 


Action: Delete the associated web service definition 
and recreate it. 


Type: SEVERE:NIDP:WSF:003 


Cause: Some Java error (probably a classpath issue) is 
causing the main authority class to not instantiate. 


Action: Review how the Access Manager product was 
installed and attempt to determine if Java class files are 
being accessed from an unexpected source. 


Type: SEVERE:NIDP:WSF:004 


Cause: This error catches all failures encountered while 
trying to load all web services. The reason will be 
different depending on where the error happened. 


Action: Try to delete and recreate the web services. 
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Event Code 


100102005 


100102006 


100102007 


100102008 


100102009 


100102010 
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Message 


Unable to access Novell 
Secret Store. 


Unable to create user profile 
object. 


Unable to instantiate 
password callback class. 


Unable to convert XML into 
Document. 


Unable to process 


WSSecurity (WSS) message. 


No WSS header found 


Remedy 


Type: SEVERE:NIDP:WSF:005 


Cause: The LDAP connection between the IDP and the 
User Store must be secure LDAP if Novell Secret Store 
is to be used as the back end storage for Credential 
Profile. 


Action: Go to the associated user store and change the 
connection type to secure LDAP. 


Type: SEVERE:NIDP:WSF:006 


Cause: A Liberty User Profile Object did not exist for the 
current user, so an attempt was made to create one. 
That attempt failed! 


Action: Determine if the named container exists and 
that the administrator user has rights to create objects 
there. 


Type: SEVERE:NIDP:WSF:007 


Cause: Could not find the password callback class in 
the classpath. 


Action: Make sure the password callback class to 
check UsernameToken that decrypts an encrypted 
message in WSS is in the classpath. 


Type: SEVERE:NIDP:WSF:008 


Cause: This error occurred when converting XML to 
Document in WSS (Receiver side). It may happen due 
to incorrect WSC requests. 


Action: Check the WSC (Sender side) request and 
resend it. 


Type:SEVERE:NIDP:WSF:009 


Cause: This error occurred when processing WSS 
headers (Receiver side). It may happen due to incorrect 
WSS headers in WSC requests. 


Action: Check the WSS headers in WSC (Sender side) 
request and resent it. 


Type: SEVERE:NIDP:WSF:010 


Cause: This error occurred when processing WSS 
headers (Receiver side). It may happen due to no WSS 
headers in WSC requests. 


Action: Check the WSS headers in WSC (Sender side) 
request and resend it. 


Event Code 


100102011 


100102012 


100102013 
100102014 
100102015 
100102016 
100102017 
100102018 
100102019 
100102020 
100102021 
100102022 
100102023 
100102024 
100102025 


100102026 
100102027 
100102028 
100102029 
100102030 
100102031 
100102032 


Message 


No processed WSS header 
found 


WSS untrusted certificate 


The Service Discovery 
Service has not been 
initialized. 


Remedy 


Type: SEVERE:NIDP:WSF:011 


Cause: This error occurred after processing WSS 
headers (Receiver side). It may happen due to incorrect 
or no WSS headers in WSC requests. 


Action: Check the WSS headers in WSC (Sender side) 
request and resend it. 


Type: SEVERE:NIDP:WSF:012 


Cause: This error occurred when validating signature 
on WSS headers (Receiver side). The certificate used 
for the signature is not trusted. 


Action: Check the certificate used to sign the message. 
The certificate is trusted if either it itself or the certificate 
of the issuer is installed in the trust store. 


Type: SEVERE:NIDP:WSF:013 
Type: SEVERE:NIDP:WSF:014 
Type: SEVERE:NIDP:WSF:015 
Type: SEVERE:NIDP:WSF:016 
Type: SEVERE:NIDP:WSF:017 
Type: SEVERE:NIDP:WSF:018 
Type: SEVERE:NIDP:WSF:019 
Type: SEVERE:NIDP:WSF:020 
Type: SEVERE:NIDP:WSF:021 
Type: SEVERE:NIDP:WSF:022 
Type: SEVERE:NIDP:WSF:023 
Type: SEVERE:NIDP:WSF:024 
Type: SEVERE:NIDP:WSF:025 


Cause: The Discovery Service has not been enabled or 
created. 


Action: Create and enable a Liberty Discovery Service 
using the Access Manager administration utility. 


Type: SEVERE:NIDP:WSF:026 
Type: SEVERE:NIDP:WSF:027 
Type: SEVERE:NIDP:WSF:028 
Type: SEVERE:NIDP:WSF:029 
Type: SEVERE:NIDP:WSF:030 
Type: SEVERE:NIDP:WSF:031 
Type: SEVERE:NIDP:WSF:032 
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Event Code 


100102033 
100103001 


100103002 
100103003 
100103004 
100103005 
100103006 
100103007 
100103008 
100103009 
100103010 
100103011 
100103012 
100103013 
100103014 
100103015 
100103016 
100103017 
100104105 


100104107 
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Message 


Web Service Consumer XML 
Configuration Parse 
Exception. 


Could not initialize Kerberos/ 
GSS 


Kerberos Configuration is not 
properly initialized 


Remedy 


Type: SEVERE:NIDP:WSF:033 
Type: SEVERE:NIDP:WSC:001 


Cause: The nidsConfigXML attribute on the nidsWsf 
object has invalid XML. 


Action: Delete the nidsConfigXML attribute and 
reconfigure WSC. 


Type: SEVERE:NIDP:WSC:002 
Type: SEVERE:NIDP:WSC:003 
Type: SEVERE:NIDP:WSC:004 
Type: SEVERE:NIDP:WSC:005 
Type: SEVERE:NIDP:WSC:006 
Type: SEVERE:NIDP:WSC:007 
Type: SEVERE:NIDP:WSC:008 
Type: SEVERE:NIDP:WSC:009 
Type: SEVERE:NIDP:WSC:010 
Type: SEVERE:NIDP:WSC:011 
Type: SEVERE:NIDP:WSC:012 
Type: SEVERE:NIDP:WSC:013 
Type: SEVERE:NIDP:WSC:014 
Type: SEVERE:NIDP:WSC:015 
Type: SEVERE:NIDP:WSC:016 
Type: SEVERE:NIDP:WSC:017 
Type: SEVERE:NIDP:USERAUTH:105 
Cause: Failure at GSS-API 


Action: Check the following according the details of the 
error message: Keytab file - validity, presently only 
understands DES; Service Principal Name (SPN) 


Type: SEVERE:NIDP:USERAUTH:107 


Cause: Kerberos Configuration is not properly initialized 
in the admin user interface 


Action: Make sure all the required configuration setting 
are properly specified in admin UI 


Event Code 


100104108 


100105001 


100105002 


100105003 


100105004 


100105005 


100105006 
100105007 


Message 


SPNEGO/Kerberos method 
not implemented 


An error happened while 
forwarding a request to a 
cluster member. 


Failed to initialize JNDI 
connections. 


Error obtaining SOAP 
response. 


Error in SOAP response 
format. 


Error executing Login Policy 
Check LDAP Extension for 
user on user store 


Remedy 


Type: SEVERE:NIDP:USERAUTH:108 


Cause: SPNEGO/Kerberos NegTokenInit not 
implemented. 


Action: NegTokenlnit token not implemented as the 
server side does not need to generate it new. No Action 
needed. 


Type: SEVERE:NIDP:APP:001 

Cause: An internal error occurred. 

Action: Evaluate the error and take appropriate action. 
Type: SEVERE:NIDP:APP:002 


Cause: NIDP attempts to create JNDI connections to 
each user store replica during NIDP startup. In this 
case, NIDP was unable to establish connections with 
the indicated host. 


Action: Ensure that the host is available and that the 
configuration information for the replica is correct. 


Type: SEVERE:NIDP:APP:003 


Cause: A SOAP request was made and a response 
was expected, but an error happened retrieving the 
response. 


Action: Evaluate the indicated reason and take 
appropriate action. 


Type: SEVERE:NIDP:APP:004 


Cause: A SOAP request was made and a response 
was expected, the response was obtained but the 
format of it was unexpected. 


Action: Evaluate the indicated reason and take 
appropriate action. 


Type: SEVERE:NIDP:APP:005 


Cause: User authenticated using X509. An additional 
check of the directory's user login policy needs to be 
made using an LDAP method extension. This check 
was successfully done using an LDAP extension. 
However, after the LDAP extension is called, it must be 
called a second time to update the user account with a 
success or failure. This second call to the extension 
failed, so directory user account status may be 
erroneous. 


Action: Check with eDirectory documentation for LDAP 
extension with OID 2.16.840.1.113719.1.39.42.100.25 


Type: SEVERE:NIDP:APP:006 
Type: SEVERE:NIDP:APP:007 


Troubleshooting 1383 


Event Code 


100105008 


100106001 
200102001 


200102002 


200102003 


200102004 


200102005 
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Message 


The audit logging system is 
not operational. 


Invalid access code found for 
web service specific user 
interaction query policy. 


Invalid access code found for 
web service specific user 
interaction modify policy. 


Unrecognized web service. 


Error writing user interaction 
access policy to the data 
store. 


Cannot read or write web 
service data because zero 
data locations are specified. 


Remedy 


Type: SEVERE:NIDP:APP:008 


Cause: The audit logging system can, in rare 
circumstances, become non-operational. 


Action: Examine the error description supplied and take 
appropriate action. 


Type: SEVERE:NIDP:IDFF:001 
Type: ERROR:NIDP:WSF:001 


Cause: The web service definition has a service level 
user interaction policy that is not ALWAYS or NEVER. 
Disallowed values are NO and ONCE. 


Action: Using Access Manager management tools, edit 
the policy associated with the web service. 


Type: ERROR:NIDP:WSF:002 


Cause: The web service definition has a service level 
user interaction policy that is not ALWAYS or NEVER. 
Disallowed values are NO and ONCE. 


Action: Using Access Manager management tools, edit 
the policy associated with the web service. 


Type: ERROR:NIDP:WSF:003 


Cause: The web service definition has a service type 
specifier (attribute nidsWsfServiceInstanceType on 
object nidsWsfService) that is not recognized. 


Action: Using Access Manager management tools, 
delete the associated web service and recreate it. 


Type: ERROR:NIDP:WSF:004 


Cause: The IDP received user interaction access policy 
from the user, but was unable to persist it to the data 
store. 


Action: Check the Access Manager Configuration 
datastore to see if it is available. 


Type: ERROR:NIDP:WSF:005 


Cause: When an IDSIS web service is reading or 
writing data it follows the configured data locations to 
know where to perform its operations. If the 
administrator has not set up any data locations then the 
operation must fail. 


Action: Add at least one data location the web service. 


Event Code Message Remedy 


200102006 Cannot read or write web Type: ERROR:NIDP:WSF:006 
service data because the first 
data location is unknown. Cause: When an IDSIS web service is reading or 


writing data it follows the configured data locations to 
know where to perform its operations. 


Action: Delete all data locations from the associated 
web service and add them back into the list. 


200102007 Unexpected error writing data Type: ERROR:NIDP:WSF:007 


to web service. 7, aa ; 
Cause: Writing to web services is prone to various 


unexpected errors. 


Action: Evaluate the reason for the error and take 
appropriate action. 


200102008 Unable to locate the cached Type: ERROR:NIDP:WSF:008 


NIDPSession object given 
session id. Cause: The user session has expired. 


Action: The user must login again. 


200102009 Cached NIDPPrincipal object Type: ERROR:NIDP:WSF:009 


has zero NIDPSubject ' , 
objects. Cause: The user session has expired. 


Action: The user must login again. 


200102010 No web service authority Type: ERROR:NIDP:WSF:010 


available. 
Cause: A web service of the provided type did not 


initialize correctly. 
Action: Delete the web service and recreate it. 
200102011 No web service available. Type: ERROR:NIDP:WSF:011 


Cause: A web service of the provided type does not 
exist, or is not enabled. 


Action: Create or enable a web service of this type. 


200102012 Unable to understand the web Type: ERROR:NIDP:WSF:012 


service request's XML. 
Cause: A web service sent a request to the IDP that 


cannot be parsed or it is missing data such that the 
request cannot be understood. 


Action: Notify your system administrator that invalid 
web service requests are being made to the system. 


200102013 Error processing web service Type: ERROR:NIDP:WSF:013 


query request. , : : 
Cause: Processing web service requests may result in 


a number of unexpected errors. 


Action: Evaluate the reason given in the error 
message, and take appropriate action. 
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Event Code 


200102014 


200102015 


200102016 


200102017 


200103001 


200103002 


200103003 


200104001 
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Message 


Error processing web service 
modify request. 


Unable to locate the user's 
local identifier in the resource 
id. 


Unable to locate a cached 
NIDPPrincipal object given the 
local id. 


Unable to locate a 
NIDPldentity object given the 
local id. 


The indicated web service is 
not available or it has been 
disabled! An attempt was 
made to access this service to 
operate on the indicated data. 


Cannot make web service 
request because there are 
zero web service resource 
offerings available. 


Unable to locate an identity id 
from the authentications 
available in the provided 
NIDPSession. 


Could not get client certificate. 


Remedy 


Type: ERROR:NIDP:WSF:014 


Cause: Processing web service requests may result in 
a number of unexpected errors. 


Action: Evaluate the reason given in the error 
message, and take appropriate action. 


Type: ERROR:NIDP:WSF:015 


Cause: The web service resource id, an identifier 
indicating what user the request is destined for, did not 
contain the information required to identify the user. 


Action: Notify your system administrator that invalid 
web service requests are being made to the system. 


Type: ERROR:NIDP:WSF:016 
Cause: The user session has expired. 
Action: The user must login again. 
Type: ERROR:NIDP:WSF:017 
Cause: The user session has expired. 
Action: The user must login again. 
Type: ERROR:NIDP:WSC:001 


Cause: The Web Service Consumer received a request 
and one of the data tokens referenced a data item that 
is not available in any of the services known to the 
Access Manager. 


Action: The system has encountered an invalid 
configuration and should be restarted by the system 
administrator. 


Type: ERROR:NIDP:WSC:002 


Cause: The Web Service Consumer received a request 
but there were zero service resource offerings provided. 
So, the web service has no destination service to which 
a request can be made. 


Action: The user must login again. 
Type: ERROR:NIDP:WSC:003 
Cause: The user session has expired. 
Action: The user must login again. 
Type: ERROR:NIDP:USERAUTH:001 


Cause: Could not get user certificate from the client 
browser 


Action: Install user X509 certificate on the client 
browser and try again. 


Event Code 


200104003 


200104004 


200104005 


200104006 


200104008 
200104009 


200104010 


200104011 


200104012 


Message 


Could not read configuration 


User Certificate 
Authentication Failed 


No matching Principal found. 


More than one Principal 
matched. 


Error loading Trust store 


Client certificate not yet valid. 


Client certificate no longer 
valid. 


The Certificate has been 
revoked. 


Error Parsing Certificate. 


Remedy 


Type: ERROR:NIDP:USERAUTH:003 
Cause: Could not read configuration out of file 


Action: Make sure the X509 config properties file is 
present. 


Type: ERROR:NIDP:USERAUTH:004 


Cause: User Certificate Authentication Failed due to the 
reasons in detailed message 


Action: Take appropriate action as per the reasons in 
the detailed message 


Type: ERROR:NIDP:USERAUTH:005 


Cause: No Principal from X509Certificate found in User 
store 


Action: Check the X509Class Method and it's attribute 
mapping profile as defined using administration tool. 
Also, make sure the matched user exists in the User 
store. 


Type: ERROR:NIDP:USERAUTH:006 


Cause: Principal from X509Certificate Multiple users 
found in User store which matched Principal from 
X509Certificate based on X509Class attribute mapping 
profile.\ 


Action: Check the X509Class Method and it's attribute 
mapping profile as defined using administrator tool. 
Also, check if multiple user exists in the User store(s). 


Type: ERROR:NIDP:USERAUTH:008 
Type: ERROR:NIDP:USERAUTH:009 
Cause: X509 certificate is valid in the future 
Action: Use a valid certificate 

Type: ERROR:NIDP:USERAUTH:010 
Cause: X509 certificate is expired 

Action: Use a valid certificate 

Type: ERROR:NIDP:USERAUTH:011 
Cause: The Certificate has been revoked 
Action: Use a valid certificate which is not revoked. 
Type: ERROR:NIDP:USERAUTH:012 


Cause: Error Parsing Certificate when performing 
certificate validations 


Action: Use a valid X509 certificate. 
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1387 


Event Code 


200104017 


200104018 


200104019 


200104020 


200104021 


200104022 


200104023 


1388 Troubleshooting 


Message 


Error getting CRL/OCSP. 


Could not verify CRL 


signature. 


Could not find Key for this 
server. 


CRL/OCSP is too old; New 
version already available. 


No Issuer Certificate found. 


Error getting OCSP 
Response. 


Error processing OCSP 
Response. 


Remedy 


Type: ERROR:NIDP:USERAUTH:017 


Cause: Could not get to the CRL/OCSP URL for 
validations. 


Action: Make sure the CRL/OCSP URLs are accessible 
Or disable validations in administration. Additionally, can 
define a different CRL/OCSP URL in the administration 
tool which the X509Class can also use for validations. 


Type: ERROR:NIDP:USERAUTH:018 
Cause: Could not verify signature on the fetched CRL 


Action: Make sure the CRL server public key/certificate 
is in NIDP/ESP trust store. 


Type: ERROR:NIDP:USERAUTH:019 


Cause: Could not find Key/Cert for NIDP/ESP server 
towards authenticating to OCSP server 


Action: Make sure the NIDP/ESP Signing keystore has 
appropriate Key/Cert in it. 


Type: ERROR:NIDP:USERAUTH:020 


Cause: During validations, the fetched CRL Or OCSP is 
stale. Newer version will be available 


Action: In case of CRLs, next attempt to fetch CRL 
should get a fresh CRL after purging the cached one. In 
case of OCSP, notify the OCSP server administrator. 


Type: ERROR:NIDP:USERAUTH:021 


Cause: Issuer of user certificate not found which is 
required for OCSP validations 


Action: Make sure the issuer of user/client certificate is 
either found in certificate-chain or in NIDP/ESP trust 
store. 


Type: ERROR:NIDP:USERAUTH:022 


Cause: Could not get OCSP Response from the OCSP 
server 


Action: Make sure its going to the right OCSP server. 
Type: ERROR:NIDP:USERAUTH:023 
Cause: OCSP response could not be processed 


Action: Make sure its going to the right OCSP server 
and that it is operating correctly. 


Event Code 


200104024 


200104025 


200104026 


200104027 


200104028 


200104029 


200104030 


200104031 


Message 


At least one parameter of 
OCSPProcessor was 
uninitialized. 


Request was already 
generated. 


OCSP response was already 
processed 


Internal error occurred in the 
OCSP Server. 


Your request did not fit the 
RFC 2560 syntax. 


Your request was not signed. 


The server was too busy to 
answer you. 


The server could not 
authenticate you. 


Remedy 


Type: ERROR:NIDP:USERAUTH:024 


Cause: At least one parameter of OCSPProcessor was 
uninitialized during OCSP validations 


Action: Make sure the NIDP/ESP Signing keystore has 
appropriate Key/Cert in it. Also, that the NIDP/ESP 
OCSP trust store has the valid public-key/certificate of 
OCSP server. 


Type: ERROR:NIDP:USERAUTH:025 


Cause: OCSP request was already generated for 
certificate(s) 


Action: Check the client certificate chain. 


Type: ERROR:NIDP:USERAUTH:026 


Type: ERROR:NIDP:USERAUTH:027 


Cause: OCSP server responded to the request with an 
internal error. 


Action: Contact OCSP server administrator. 
Type: ERROR:NIDP:USERAUTH:028 


Cause: OCSP server responded to the request with 
malformed request message. 


Action: Contact OCSP administrator and check the 
request. 


Type: ERROR:NIDP:USERAUTH:029 
Cause: Request to OCSP server needs to be signed. 


Action: Enable signing of OCSP requests in X509Class 
administration. 


Type: ERROR:NIDP:USERAUTH:030 


Cause: OCSP server is too busy to respond to 
requests. 


Action: Contact OCSP server administrator. 
Type: ERROR:NIDP:USERAUTH:031 


Cause: OCSP server could not authenticate Novell 
Identity server. 


Action: Make sure Signing of OCSP requests is 
enabled and NIDP signing keystore has appropriate key 
in it. Also, make sure the OCSP server trusts Nidp 
server. 
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Event Code 


200104032 


200104033 


200104034 


200104035 


200104036 


200104037 


200104038 


200104039 


1390 Troubleshooting 


Message 


Unknown OCSPResponse 
status code. 


No valid OCSPResponse 
obtained. 


Response was generated in 
the future. 


Error verifying responder 
certificate. 


Response seems to be signed 
with untrusted certificate. 


The received responder id 
does not match your 
responder certificate. 


Could not verify OCSP server 
response. 


No client certificates inside 
OCSP response. 


Remedy 


Type: ERROR:NIDP:USERAUTH:032 


Cause: OCSP server responded to the request with 
unknown status code. 


Action: Contact OCSP server administrator. 
Type: ERROR:NIDP:USERAUTH:033 
Cause: Invalid OCSP response obtained. 


Action: Check the OCSP server response version and 
contact administrator. 


Type: ERROR:NIDP:USERAUTH:034 
Cause: OCSP response is not yet valid. 


Action: Disable OCSP validations Or Contact OCSP 
server administrator. 


Type: ERROR:NIDP:USERAUTH:035 


Cause: This may happen when reading the OCSP trust 
store during OCSP validations. 


Action: Make sure OCSP trust store exists on NIDP 
server. 


Type: ERROR:NIDP:USERAUTH:036 


Cause: OCSP server trusted-root certificate not found 
in OCSP trust store. 


Action: Import OCSP server trusted root in Nidp's 
OCSP trust store. 


Type: ERROR:NIDP:USERAUTH:037 


Cause: The response ID received in OCSP response 
does not match. 


Action: Make sure NIDP's OCSP trust store has the 
right OCSP server public-key certificate. 


Type: ERROR:NIDP:USERAUTH:038 
Cause: OCSP server response is incorrect. 


Action: Verify the OCSP server URL. Make sure NIDP's 
OCSP trust store has the right OCSP server public-key 
certificate. 


Type: ERROR:NIDP:USERAUTH:039 
Cause: Empty response from OCSP server. 


Action: Verify the OCSP server URL. 


Event Code Message Remedy 


200104040 Number of certificates inside Type: ERROR:NIDP:USERAUTH:040 
OCSP response does not fit to 


request. Cause: OCSP response does not contain the requested 
number of certificate status. 
Action: Verify the OCSP server URL. 
200104041 Certificate was revoked in the Type: ERROR:NIDP:USERAUTH:041 
future. 
Cause: OCSP response not yet valid. 
Action: Verify the OCSP server URL. 
200104042 Received certificate twice or Type: ERROR:NIDP:USERAUTH:042 
one, that was not requested. 
Cause: OCSP response does not match request. 
Action: Verify the OCSP server URL. 
200104043 Request was not accepted. Type: ERROR:NIDP:USERAUTH:043 
Cause: Could not connect to OCSP server. 
Action: Verify the OCSP server URL. 
200104044 Wrong response type (not Type: ERROR:NIDP:USERAUTH:044 
application/ocsp-response). 
Cause: Malformed OCSP response. 
Action: Verify the OCSP server URL. 
200104045 No OCSPResponse Type: ERROR:NIDP:USERAUTH:045 
message. 
Cause: No OCSPResponse message. 
Action: Verify the OCSP server URL. 
200104046 Could not read whole Type: ERROR:NIDP:USERAUTH:046 
OCSPResponse. 
Cause: Malformed OCSP response. 
Action: Verify the connection to OCSP server URL. 
200104047 Exception Occurred. Type: ERROR:NIDP: USERAUTH:047 
Cause: Error getting CRL. 


Action: Verify the connection to CRL server URL. 


200104051 Unsupported critical extension Type: ERROR:NIDP:USERAUTH:051 


OID(s). 
Cause: Some Critical extension OID(s) not understood. 
Action: Check the certificate for unsupported critical 
extensions. If needed, add the processing of the critical 
extension in NDPCertPathChecker class. 
200104053 Error processing CRL Type: ERROR:NIDP:USERAUTH:053 
Response. 


Cause: Error processing CRL Response. 


Action: Check X509class config and user/client 
certificate CRL extension. 
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Event Code 


200104054 


200104055 


200104057 


200104058 


200104059 


200104060 


200104061 


200104062 


1392 Troubleshooting 


Message 


Error processing certificate 
validations. 


Protocol not supported or 
none specified. 


Unable to do X509 Certificate 
based authentication over non 
SSL (HTTP). 


Overwrite a real or temp user 
error. 


User store connection error. 


Problem in fetching password. 


Problem in provisioning the 
user. 


Auto provisioning successful. 


Remedy 


Type: ERROR:NIDP:USERAUTH:054 
Cause: Error processing CRL/OCSP validations. 


Action: Check X509class config and user/client 
certificate CRL extension. 


Type: ERROR:NIDP:USERAUTH:055 
Cause: Transport protocol not supported to fetch CRL. 


Action: Currently, CRLs can be fetched over http and 
LDAP protocols. Make sure the X509class config and/or 
user/client certificate CRL extension does not have any 
other transport protocol specified. 


Type: ERROR:NIDP:USERAUTH:057 
Cause: URL protocol is HTTP 

Action: URL protocol needs to be HTTPS 
Type: ERROR:NIDP:USERAUTH:058 


Cause: User is not identified in the authenticated user 
session. 


Action: Authenticate with a valid authentication contract 
to identify the user. 


Type: ERROR:NIDP:USERAUTH:059 
Cause: LDAP replica connection error 


Action: Check the connectivity from Identity Server to 
LDAP replicas. 


Type: ERROR:NIDP:USERAUTH:060 
Cause: Error while fetching user password 


Action: Check the password policy for the user and 
verify that admin has permission to retrieve the 
password for that user. 


Type: ERROR:NIDP:USERAUTH:061 


Cause: Error while auto User provisioning for password 
fetch class. 


Action: Check whether admin has permission to create 
user and modify user’s attributes in the LDAP store. 


Type: INFO:NIDP:USERAUTH:062 


Scenario: Password fetch class was successful in auto 
provisioning user. 


Event Code 


200104063 


200104064 


200104065 


200104066 


200104100 


200104101 


200104102 


200104103 


Message 


Universal password retrieval 
error. 


Simple password retrieval 
error. 


User lookup failed. 


Client Integrity Check (CIC) 
failed. 


Error processing Authorization 
header 


Error processing SPNEGO/ 
Kerberos 


No Kerberos Principal found in 
the token 


No SPNEGO Token found 


Remedy 


Type: ERROR:NIDP:USERAUTH:063 


Cause: Universal password retrieval error with 
password fetch class. 


Action: Check the universal password policy for the 
user and verify that admin has permission to retrieve the 
password for that user. 


Type: ERROR:NIDP:USERAUTH:064 


Cause: Simple password retrieval error with password 
fetch class. 


Action: Check the simple password policy for the user 
and verify that admin has permission to retrieve the 
password for that user. 


Type: ERROR:NIDP:USERAUTH:065 


Cause: User lookup failed for the Distinguished Name 
(DN) with password fetch class. 


Action: Create a user DN in the eDirectory from which 
the user password is retrieved. 


Type: ERROR:NIDP:USERAUTH:066 
Cause: CIC failed. 


Action: Check if the required software is available on 
the system. Check the CIC class is configured properly. 
Check the logs on java console on the system. 


Type: ERROR:NIDP:USERAUTH:100 
Cause: Could not process HTTP Authorization header 


Action: Try with correct authorization header with 
base64 encoded SPNEGO token 


Type: ERROR:NIDP:USERAUTH:101 


Cause: Error processing SPNEGO/Kerberos. The 
cause is included in detailed message 


Action: Take action as per the detailed error message 
Type: ERROR:NIDP:USERAUTH:102 
Cause: Failure at GSS-API 


Action: Make sure the Kerberos keytab file is 
generated correctly by KDC 


Type: ERROR:NIDP:USERAUTH:103 
Cause: No SPNEGO Token found in the request 


Action: Include the SPNEGO token in the request to 
use this authentication 
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Event Code 


200104104 


200104106 


200104109 


200104110 


200104111 


200104112 


200107005 


300101002 


300101003 


1394 Troubleshooting 


Message 


GSS Context already 
established 


Unrecognized SPNEGO 
Token 


Malformed SPNEGO 
NegTokenInit 


Malformed SPNEGO Token 
field 


Multiple users matched in the 
user stores 


No user matched in the user 
stores 


Error building certificate chain 
during validations. 


An authenticated subject is 
required. 


An authentication principal is 
required. 


Remedy 


Type: ERROR:NIDP:USERAUTH:104 
Cause: GSS Context already established 
Action: Close the browser and try again 
Type: ERROR:NIDP:USERAUTH:106 
Cause: Unrecognized SPNEGO Token 


Action: Include the correct SPNEGO token in the 
request to use this authentication 


Type: ERROR:NIDP:USERAUTH:109 

Cause: Malformed token NegTokenInit 

Action: Try again with correct NegTokenlnit token 
Type: ERROR:NIDP:USERAUTH:110 

Cause: Malformed SPNEGO Token field 

Action: Try again with correct NegTokenInit token 
Type: ERROR:NIDP:USERAUTH:111 

Cause: Multiple users matched in the user stores 
Action: Make sure the users are unique in user stores 
Type: ERROR:NIDP:USERAUTH:112 

Cause: No user found in the user stores 


Action: Make sure the user attribute (as defined in 
admin Ul) is populated in correct format. 


Type: ERROR:NIDP::005 


Cause: This could occur when all the CDPs are 
unreachable. 


Action: Change the Certificate with correct CDPs or 
make sure CDP is up and able to serve. 


Type: WARN:NIDP:USERMSG:002 


Cause: An action that can only be performed by an 
authenticated user was attempted. 


Action: Provide proper user credentials and retry 
desired action. 


Type: WARN:NIDP:USERMSG:003 


Cause: An action that can only be performed by an 
authenticated user was attempted. 


Action: User must be authenticated to perform 
operation. 


Event Code Message Remedy 


300101004 Identity does not exist oris not Type: WARN:NIDP:USERMSG:004 


specified. 
Cause: An action was attempted that requires a 
federated identity to exist. 
Action: Create a federated link prior to performing the 
action. 
300101005 Invalid or no provider is Type: WARN:NIDP:USERMSG:005 
specified. 


Cause: An action was requested related to a trusted 
provider that does not exist. 


Action: Add the desired provider as a trusted entity or 
check for invalid access to system. 


300101006 An authenticated session is Type: WARN:NIDP:USERMSG:006 


required. 
Cause: An action that can only be performed by an 
authenticated user was attempted. 
Action: Provide proper user credentials and retry 
desired action. 
300101007 Invalid artifact. Type: WARN:NIDP:USERMSG:007 


Cause: An artifact was received from an identity 
provider that is invalid or has not been used within a 
reasonable time frame. 


Action: Make sure that the provider sending the artifact 
is trusted or check for possible security intrusions. 


Troubleshooting 1395 


Event Code 


300101008 


300101009 


300101010 


300101011 


1396 Troubleshooting 


Message 


No assertion returned in 
response. 


No authentication context 
specified message in the 
assertion. 


Invalid issuer. 


Response does not match 
request. 


Assertion is being replayed. 


Remedy 


Type: WARN:NIDP:USERMSG:008 


Cause: Assertions will not be returned in a response 
whenever authentication at the identity provider fails. 
The cause for this can include invalid configurations and 
canceling the authentication process at the identity 
provider. 


This response is also returned when a user has reached 
the maximum number of sessions and then attempts to 
access a protected resource that requires 
authentication. 


Action: Make sure that both the identity and service 
providers are configured correctly to trust each other. 
Provide proper credentials during the authentication 

process at the identity provider. 


Cause: Protected resources are configured to access 
using external contracts, which are being executed at 
the external identity provider. These contracts are not 
configured to be satisfied by any of the external identity 
provider. 


Action1: Verify the external identity provider satisfiable 
contract list at the service provider and ensure that 
these external contracts are configured under the 
satisfiable list. 


Action 2: Verify the external contract definition at the 
identity provider and make sure that this contract 
definition with the matching allowable class or URI is 
available. 


NOTE: URI specifies a value that uniquely identifies the 
contract from all other contracts. 


Type: WARN:NIDP:USERMSG:009 


Cause: A response was received from a provider that is 
not trusted. 


Action: Make sure intended provider is trusted or check 
for possible intrusions. 


Type: WARN:NIDP:USERMSG:010 


Cause: A response was received for a request that was 
not issued. 


Action: Retry action and check for possible intrusion. 
Type: WARN:NIDP:USERMSG:011 


Cause: An assertion has been received that was 
already used to authenticate a user at the service 
provider. 


Action: This is a security mechanism that if persists 
may require some investigation to determine who is 
trying to replay the assertion. Assertions are only good 
for single use. 


Event Code 


300101012 


300101013 


300101014 


300101015 


300101016 


Message 


Assertion does not contain an 
authentication statement. 


Unable to validate the subject 
of the assertion. 


Assertion not yet valid. 


Assertion no longer valid. 


No matching audience. 


Remedy 


Type: WARN:NIDP:USERMSG:012 


Cause: An identity provider has sent an assertion that is 
not complete. 


Action: Check with administrator of trusted provider to 
determine why statement is not being sent. 


Type: WARN:NIDP:USERMSG:013 


Cause: A subject may not have been sent in the 
assertion or was not valid. This check protects from 
certain assertion attacks. 


If the time is not in sync between the identity provider 
and the service provider, the subject is invalid because 
of the timestamp sent with the subject. 


Action: If persistent, check the protocol message sent 
for a time discrepancy between the providers or a 
missing subject, then notify the administrator of the 
trusted site. 


For more information, see “Federation with External 
SAML 2.0 Partner Gives 300101013 Error” (http:// 
www.novell.com/support/php/ 
search.do?cmd=displayKC&docType=kc&externalld=39 
03427 &sliceld=2&docTypelD=DT_TID_1_1&dialogID=6 
9860557 &stateld=0%200%2069862016). 


Type: WARN:NIDP:USERMSG:014 


Cause: An assertion was received that is not valid until 
sometime in the future. 


Action: Check server's clock for accuracy. Attempt to 
validate the clock accuracy of the computer generating 
the assertion. 


Type: WARN:NIDP:USERMSG:015 


Cause: An assertion was received that had a time 
validity period that is in the past. 


Action: Check server's clock for accuracy. Attempt to 
validate the clock accuracy of the computer generating 
the assertion. Try to authenticate again. 


Type: WARN:NIDP:USERMSG:016 


Cause: An assertion was received that was not 
intended for your server. 


Action: Determine the origin of the assertion and make 
sure that you want to accept assertions from it. 


For more information, see “Access Manager 300101016 
Error - No Matching Audience” (http:/Awww.novell.com/ 
support/php/ 
search.do?cmd=displayKC&docType=kc&externalld=32 
60366&sliceld=2&docTypelD=DT_TID_1_1&dialogID=6 
9860436&stateld=0%200%2069856899). 
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Event Code 


300101017 


300101018 


300101020 


300101021 


300101022 


300101023 


300101024 


300101025 
300101026 
300101027 


1398 Troubleshooting 


Message 


Missing or invalid signature on 
assertion. 


Missing or invalid signature on 
request/response. 


Digital signature is required. 


Signature validation failed. 


An undetermined problem in 
the message format has 
occurred. 


User lookup failed. 


Failed to load java class. 


Remedy 


Type: WARN:NIDP:USERMSG:017 
Cause: The identity provider did not sign. 


Action: Check with provider of assertion to determine 
why assertion is not signed. 


Type: WARN:NIDP:USERMSG:018 


Type: WARN:NIDP:USERMSG:020 


Cause: A protocol message was received that was 
expected to be digitally signed, but was not. 


Action: It may be necessary to contact the trusted 
provider administrator to determine why the message is 
not signed. Make sure authentication request signing 
settings match those for the trusted provider. 


Type: WARN:NIDP:USERMSG:021 


Cause: The digital signature of a protocol message 
could not be verified using the public key obtained in the 
metadata of a trusted provider. 


Action: Update the metadata of trusted provider. This 
should ensure you have the latest signing certificate. 


Type: WARN:NIDP:USERMSG:022 


Cause: An error was detected in the exchange of either 
a Liberty or SAML protocol message. 


Action: Turn logging/tracing on to print out the message 
that is problematic. It may be necessary to contact 
Novell Technical Services in this case. 


Type: WARN:NIDP:USERMSG:023 


Cause: An attempt to identify a user failed while 
attempting to complete a federation at the server. 


Action: Check the configuration for identifying users for 
the trusted provider and ensure the specified method 
can resolve to a single user in your directory. 


Type: WARN:NIDP:USERMSG:024 


Cause: A Java class failed to be loaded during program 
execution. 


Action: Check the logs to determine the class that is 
failing to load. Make sure the class being loaded is in 
the classpath of the JVM. 


Type: WARN:NIDP:USERMSG:025 
Type: WARN:NIDP:USERMSG:026 
Type: WARN:NIDP:USERMSG:027 


Event Code Message Remedy 


300101028 SOAP TLS authorization Type: WARN:NIDP:USERMSG:028 


failed. 
Cause: SSL mutual authentication is being used to 


authenticate a SOAP back channel session and the 
credentials cannot be validated. 


Action: Make sure certificates for back channel 
communications are trusted on each end. 


For more information, see “Access Manager 300101028 
- SOAP TLS Authorization Failed” (http:// 
www.novell.com/support/php/ 
search.do?cmd=displayKC&docType=kc&externalld=38 
13149&sliceld=2&docTypelID=DT_TID_1_1&dialogID=6 
9848431 &stateld=0%200%2069844751). 


300101029 Type: WARN:NIDP:USERMSG:029 
300101030 SOAP fault. Type: WARN:NIDP:USERMSG:030 


Cause: An error was detected in the transmission of 
protocols using SOAP. 


Action: Turn tracing on and look for any obvious 
causes for the problem. 


300101031 Received an identity thatdoes Type: WARN:NIDP:USERMSG:031 


not resolve to the current a , AE 
logged in user. Cause: This is caused when a user is logged in with 


one identity and then attempts to authenticate as the 
identity of another user. For a given session, all 
authentications must resolve to the same user. 


Action: Log out of the current user and log in again as 
the desired user. 


300101032 Assertion is expired. Type: WARN:NIDP:USERMSG:032 


Cause: The use of the assertion to authenticate the 
server did not occur within the time limits specified by 
the assertion. 


Action: Try and re-authenticate. Determine if there are 
any network latencies that may cause the assertion not 
to arrive in a timely fashion. Look for misuse of the 
assertion. 


300101033 IDP return authentication Type: WARN:NIDP:USERMSG:033 


failure. 
Cause: An IDP's attempt to authenticate the server was 


unsuccessful. This particular authentication came from 
the IDP's intersite transfer service and was not 
requested by the server. 


Action: Check at the IDP for a reason why the 
authentication was a failure. It may just be necessary to 
attempt authentication again. 
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Event Code Message Remedy 


300101034 No target is defined. Type: WARN:NIDP:USERMSG:034 


Cause: A request was made of the server's intersite 
transfer service without specifying a target resource. 


Action: Requests for the intersite transfer service must 
include an id of the intended service provider to be 
authenticated as well as the target resource to be 
displayed. To avoid this error, provide an 
&amp;TARGET="value" on the URL. 


300101035 Type: WARN:NIDP:USERMSG:035 


300101036 Not enough memory to Type: WARN:NIDP:USERMSG:036 


process request. 
Cause: The system does not have enough memory to 


complete the requested action. 


Action: Wait a few moments for memory to free up and 
retry request. It may be necessary to add additional 
memory to the server. 


300101037 Server is not in a running Type: WARN:NIDP:USERMSG:037 
oe Cause: A request was made of the server that can only 
be performed when the server is in a running state. 
Action: Start the server. 
300101038 JSP file not found. Type: WARN:NIDP:USERMSG:038 


Cause: An attempt was made to load a JSP page that 
does not exist. 


Action: Determine the JSP not loading and make sure it 
is in the correct location. 


300101039 Invalid authentication Type: WARN:NIDP:USERMSG:039 


credentials were provided. 
Cause: A user has attempted to authenticate to the 


system with credentials that are not valid for the 
account. 


Action: User needs to enter correct credentials. 
300101040 User password has expired. Type: WARN:NIDP:USERMSG:040 


Cause: A user has attempted to authenticate to the 
system with a password that is expired. 


Action: The user needs to create a new password. 


1400 Troubleshooting 


Event Code Message Remedy 


300101041 User account identification Type: WARN:NIDP:USERMSG:041 


failed. 
Cause: Account identification can fail due to: 1. User 


cancels authentication request 2. User cannot be 
uniquely identified by Matching Expression 3. 
Necessary attributes to do user matching or 
provisioning were not obtained. 


Action: Check Account Identification configuration for 
the trusted provider and make sure that necessary 
attributes are available. If using Matching Expressions, 
make sure that they include attributes that can resolve 
to a single user. If using Provisioning, make sure 
required attributes are all available in the defined 
attribute set for the trusted provider. 


For more information, see “Access Manager Error 
300101041 Provisioning New Users Using SAML2” 
(http://www.novell.com/support/php/ 
search.do?cmd=displayKC&docType=kc&externalld=32 
19302&sliceld=1&docTypelID=DT_TID_1_1&dialogID=6 
9780245&stateld=0%200%20697 78277). 


300101042 Invalid assertion conditions. Type: WARN:NIDP:USERMSG:042 


Cause: A set of conditions that are not understood were 
sent as part of an assertion. 


Action: Check with the provider of the assertion to 
determine what these conditions are and why they are 
being sent. 


300101046 Unknown URL host. Type: WARN:NIDP:USERMSG:046 


Action: Use logs to determine the problematic host and 
determine why DNS is failing. 


300101047 An untrusted provider is being Type: WARN:NIDP:USERMSG:047 


referenced in a request or a , , , , 
response. Action: Use logs to determine the provider that is 


untrusted and then create a trusted relationship if 
desired. 


300101048 The LDAP servers are too Type: WARN:NIDP:USERMSG:048 


busy to accept more users. B 
Cause: There are too many threads waiting to get an 


available LDAP connection. The LDAP servers are too 
busy to accept more users. 


Action: Wait a few moments for the LDAP requests to 
be processed and retry the request. It may be 
necessary to add additional LDAP servers or upgrade 
the hardware specifications of the existing LDAP 
servers. 


300101049 The HTTPS protocol was not Type: WARN:NIDP:USERMSG:049 
used to access this 
authentication card. Cause: Accessing the site was done via http, not https. 


Action: Access the site again using https. 
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Event Code 


300101050 


300101051 


300101052 


300101053 


300101054 


300101057 


300101058 


1402 Troubleshooting 


Message 


The Authentication Card 
specified is not valid. 


The user’s session limit has 
been reached. 


A response was expected at 
the url but none was found. 


CardSpace authentication 
profile failed to load. 


CardSpace authentication fails 
because a required attribute is 
not in assertion. 


Request to broker an 
authentication to a target SP 
denied 


Request to broker on 
authentication to a target SP 
denied 


Remedy 


Type: WARN:NIDP:USERMSG:050 


Cause: An invalid card identifier was used, most likely 
due to modifying a url. 


Action: Specify cards to use only by clicking them. 
Ensure that the PID in the login URL exactly matches 
the entity ID specified in the metadata. 


Type: WARN:NIDP:USERMSG:051 


Cause: User has already logged in the maximum 
allowable times. 


Action: Logout of one or more sessions. 
Type: WARN:NIDP:USERMSG:052 


Cause: The wrong endpoint may be accessed for the 
operation desired. 


Action: Check the action being performed against the 
url/endpoint being accessed. 


Type: WARN: NIDP:USERMSG:053 


Cause: Trusted provider failed to load (probably due to 
certificate errors). 


Action: Check the certificates for the trusted provider 
and make sure they are valid. 


Type: WARN:NIDP:USERMSG:054 


Cause: A required attribute was not returned in the 
assertion provided by an STS. 


Action: Check the attribute value at the STS, or make 
the attribute optional. 


Type: WARN:NIDP:USERMSG:057 


Cause: Request to broker an authentication to a target 
Service Provider denied, either the Identity Provider or 
target Service Provider are part of a brokering group, 
but both does not belong to same group. 


Action: Check the brokering group to verify if the 
Identity Provider and target Service Provider belong to 
the same group. 


Type: WARN:NIDP:USERMSG:058 


Cause: Request to broker on authentication to a target 
Service Provider denied because broker policy 
evaluation resulted in denying. 


Action: Check the brokering rule and try to access with 
the valid user. 


Event Code Message Remedy 


300101059 Error in processing the broker Type: WARN:NIDP:USERMSG:059 


request. 
Cause: Could not validate the request to broker on 


authentication to a target service provider. 


Action: Read the error description supplied and take 
appropriate action. 


300101060 Assertion does not contain Type: WARN:NIDP:USERMSG:060 


valid authentication statement. 
Cause: An assertion has been received, which does not 


contain valid declaration/class statement. 


Action: Authentication response statement will be 
validated against the authentication request statement. 
Check the contract definition in the service provider for 
the authentication statement received from the Identity 
Provider. Check if the requested statement matches the 
response statement or response statement's 
authentication level is greater than the requested one. 


300101061 Failed to obtain consent for Type: ERROR:NIDP:USERMSG:061 


the federation. 
Cause: This is a message to users if they have declined 


the consent. If it is a valid federation consent, accept the 
consent in the next attempt, else deny the same. 


Action: In a federated setup using the name identifier 
as persistent, if you make an Intersite Transfer Service 
request for the first time federation, users will be asked 
to provide their consent and they select No. 


300101062 An Identity Provider response Cause: When you configure a policy for a spsend 
was received that failed to request to SAML 2.0, the user is denied the policy rule, 
authenticate this session. and a message is displayed. 


Action: You are accessing an URL that is not intended 
for you. Contact your administrator. 


300102001 No Discovery Service Type: WARN:NIDP:WSF:001 
Configured! Unable to create 
the requested resource Cause: The system administrator did not create or 
offering! enable a Discovery service. 


Action: Create or enable a Discovery web service. 


300102002 Unable to find user object with Type: WARN:NIDP:WSF:002 


identifier. 
Cause: An LDAP search was performed for a user 


object with a given identifier. This identifier may be a 
GUID. The search resulted in zero hits. This usually 
means that web service data cannot be read or written 
for the user. 


Action: The user needs to login again. 
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Event Code 


300102003 


300102004 


300102005 


300102006 


300102007 


300102008 


300102009 


1404 Troubleshooting 


Message 


Unrecognized select string for 
service. 


Unable to process web 
service query request! Select 
string missing! 


Unable to perform trusted 
user interaction service 
request. Web service authority 
was not found. 


Unable to perform trusted 
user interaction service 
request. Unable to obtain 
trusted user interaction 
service description from 
SOAP headers. 


Unable to perform trusted 
user interaction service 
request. No trusted user 
interaction service description 
provided in SOAP headers. 


Trusted user interaction 
service failed. 


Error creating user interaction 
redirection request. 


Remedy 


Type: WARN:NIDP:WSF:003 


Cause: The select string (XPath) is either incorrectly 
formed or not supported by the web service. 


Action: The system administrator must enable services 
to support the select string. 


Type: WARN:NIDP:WSF:004 


Cause: The select string (XPath) is not in the web 
service query request. 


Action: Inform your system administrator that an 
improperly formatted web service request is being 
made. 


Type: WARN:NIDP:WSF:005 
Cause: An internal system error. 


Action: The system has encountered an invalid 
configuration and should be restarted by the system 
administrator. 


Type: WARN:NIDP:WSF:006 


Cause: The web service making the request did not 
provide valid or complete information about the trusted 
user interaction service. 


Action: The system administrator must complete the 
definition of the trusted interaction service. 


Type: WARN:NIDP:WSF:007 


Cause: The web service making the request did not 
provide valid or complete information about the trusted 
user interaction service. 


Action: The system administrator must complete the 
definition of the trusted interaction service. 


Type: WARN:NIDP:WSF:008 


Cause: There are various unexpected reasons for the 
failure of a trusted user interaction service request to 
fail. 


Action: Evaluate the reason and take the appropriate 
actions. 


Type: WARN:NIDP:WSF:009 


Cause: There was an error converting the redirect 
request to an XML DOM. 


Action: Evaluate the reason and take the appropriate 
actions. 


Event Code 


300102010 


300102011 


300102012 


300102013 


300102014 


300102015 


300102016 


Message 


Unable to perform user 
interaction redirection request. 
User intervention service not 
found. 


Error reading data from LDAP 
data attribute plugin. 


Error writing data to LDAP 
data attribute plugin. 


Cannot read/write Credential 
Profile data because the 
user's LDAP user store 
distinguished name is not 
available. 


A Web Service request was 
received for a user, but the 

session for that user is not 

found. 


A Web Service request was 
received for a user, but the 
session for that user has 
insufficient data in it. 


A Web Service request was 
received for a user, but the 
Liberty User Profile object for 
that user is unavailable. 


Remedy 


Type: WARN:NIDP:WSF:010 


Cause: There must be an interaction service on the IDP 
creating the user interaction redirection request. 


Action: If it does not exist, using Access Manager 
management tools, create one. 


Type: WARN:NIDP:WSF:011 


Cause: If a web service's data locations includes LDAP, 
then LDAP data attribute plugins are used to read data 
from the LDAP user store. This error provides 
descriptions of various errors that can happen while 
doing this. 


Action: Evaluate the reason and take the appropriate 
actions. 


Type: WARN:NIDP:WSF:012 


Cause: If a web service's data locations includes LDAP, 
then LDAP data attribute plugins are used to write data 
to the LDAP user store. This error provides descriptions 
of various errors that can happen while doing this. 


Action: Evaluate the reason and take the appropriate 
actions. 


Type: WARN:NIDP:WSF:013 


Cause: All Credential Profile reads and writes end up 
operating on a user object in a user store. If this user 
object cannot be found, then the operation must fail. 
This may happen if a temporary identifier is being used 
for the authentication. 


Action: Use a permanent federation to the service 
provider if your system allows it. 


Type: WARN:NIDP:WSF:014 


Cause: The user's login has timed out and has been 
removed from the system. 


Action: The user must login again. 
Type: WARN:NIDP:WSF:015 

Cause: An internal error has occurred. 
Action: The user must login again. 
Type: WARN:NIDP:WSF:016 

Cause: An internal error has occurred. 


Action: Make sure the administrator user has rights to 
read, write and create Liberty User Profile objects in the 
configuration data store. 
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Event Code 


300102017 


300102018 


300102019 


300102020 


300102021 
300102022 
300103001 


300103002 


1406 Troubleshooting 


Message 


A Web Service request was 
received for a user, and 
attempt to read the requested 
attributes from the Liberty 


User Profile object was made, 


but an error occurred. 


A Web Service request was 
received for a user, While 
reading user data from an 


LDAP user object, a mismatch 


occurred because the LDAP 
attribute is multi-valued, but 
the Liberty attribute is single- 
valued. 


The user used an X509 


Certificate to authenticate and 
we tried to put the cert into the 
SecretStore as a Base64 DER 


encoded cert, but we got an 
encoding error from the 
security layer when trying to 
get the DER encoded cert. 
Result is that there will not be 
a X509 Certificate in Secret 
Store for this user. 


A SAMLAssertion was 
requested for a given user. 
While generating the 
SAMLAssertion an error 
occurred. 


The web service request did 
not return a response within 
the protocol timeout limit. 
Request abandoned. 


An unexpected error 
happened in the web service 
consumer while processing a 
web service request. 


Remedy 


Type: WARN:NIDP:WSF:017 
Cause: An internal error has occurred. 


Action: Evaluate the reason and take the appropriate 
actions. 


Type: WARN:NIDP:WSF:018 


Cause: A multi-valued LDAP attribute has been 
mapped to a single-valued Liberty attribute. 


Action: Change the attribute mapping. 


Type: WARN:NIDP:WSF:019 
Cause: The X509 certificate cannot be encoded. 


Action: Review the type of X509 certificates that are 
being used for authentication. 


Type: WARN:NIDP:WSF:020 
Cause: The SAMLAssertion cannot be created. 


Action: Review the reason for the failure and take 
appropriate actions. 


Type: WARN:NIDP:WSF:021 
Type: WARN:NIDP:WSF:022 
Type: WARN:NIDP:WSC:001 


Cause: The web service consumer waited for the web 
service request to return a response, but it did not 
during the allowed waiting period. 


Action: This waiting period may be increased by click 
Access Manager > Identity Servers > Edit > Liberty > 
Web Service Consumer, and setting the Protocol 
Timeout to a higher value. 


Type: WARN:NIDP:WSC:002 


Cause: There are various reasons why a web service 
request could fail. 


Action: Evaluate the reason and take appropriate 
actions. 


Event Code Message Remedy 


300103003 Web service consumer Type: WARN:NIDP:WSC:003 


request pending data packet 
id is not available in request. Cause: After user interaction, processing of the original 


request returns to the web service consumer. A data 
packet containing information about how to continue the 
request is cached on the web service consumer. The id 
of that packet must be passed through all redirections 
and requests associated with the user interaction. If that 
id is not available when the web service consumer 
regains control, then the request cannot continue. 


Action: Submit the request again. 


300103004 The Web service consumer Type: WARN:NIDP:WSC:004 
request pending data packet 


with the indicated id is not Cause: After user interaction, processing of the original 
available in web service request returns to the web service consumer. A data 
consumer's cache. packet containing information about how to continue the 


request is cached on the web service consumer. The id 
of that packet must be passed through all redirections 
and requests associated with the user interaction. That 
id will be used to access the pending data packet when 
the web service consumer regains control. If the 
pending data packet with the corresponding id is no 
longer available on the system, then the request cannot 
continue. The data packet may have timed out. 


Action: Submit the request again. 


300104049 Could not find NIDP PKIX Type: WARN:NIDP:USERAUTH:049 


Certificate Path Checker 
Class. Cause: PKIX Certificate Path Checker Class not found. 


Action: Warning message that PKIX Certificate Path 
Checker Class not found. This optional class is used to 
process custom certificate extensions. If required, this 
class needs to be in NIDP classpath. It may not be 
present on ESP. 


300104050 Could not instantiate NIDP Type: WARN:NIDP:USERAUTH:050 


PKIX Certificate Path Checker 
Class. Cause: Incorrect class constructor. 


Action: Make sure the class has the right constructor. 


300105001 No user Login Policy Check Type: WARN:NIDP:APP:001 


LDAP Extension method 
available on user store. Cause: User authenticated using X509. An additional 


check of the directory's user login policy needs to be 
made using an LDAP method extension. However, the 
directory indicated does not support the required LDAP 
extension method. 


Action: Make sure the LDAP extension method with 
OID 2.16.840.1.113719.1.39.42.100.25 is present in the 
user store. Versions 8.7.3 and greater of eDirectory 
should support this method. 


300105002 Type: WARN:NIDP:APP:002 
300105003 Type: WARN:NIDP:APP:003 
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Event Code Message Remedy 


300105004 Type: WARN:NIDP:APP:004 
300105005 Type: WARN:NIDP:APP:005 
300105006 Type: WARN:NIDP:APP:006 
300105007 Type: WARN:NIDP:APP:007 
300105008 Type: WARN:NIDP:APP:008 
300105009 Type: WARN:NIDP:APP:009 
300105010 Type: WARN:NIDP:APP:010 
300105011 Type: WARN:NIDP:APP:011 
300105012 Type: WARN:NIDP:APP:012 
300105013 Type: WARN:NIDP:APP:013 
300105014 Type: WARN:NIDP:APP:014 
300105015 Type: WARN:NIDP:APP:015 
300105016 Type: WARN:NIDP:APP:016 
300105017 Type: WARN:NIDP:APP:017 
300105018 Type: WARN:NIDP:APP:018 
300105019 Type: WARN:NIDP:APP:019 
300105020 Type: WARN:NIDP:APP:020 


300105021 Unable to delete unneeded Type: WARN:NIDP:APP:21 


Image Pool Image File. 
Cause: On startup, the NIDP Image Pool is 


synchronized from eDirectory to the file system. This 
allows HTML pages to access images from a well 
known file system structure. Part of synchronization 
process involves deleting from the file system images 
that no longer exist in eDirectory. Also, the reverse is 
true, images that are new to eDirectory and do not yet 
exist on the file system are created in directories that 
reflect the image set. File system errors may occur 
during this synchronization process if a file or directory 
cannot be deleted or created. 


Action: Ensure that no errant files are copied or 
directories manually created in the file system path 
[TOMCAT_HOME}]/webapps/nidp/images/pool. Make 
sure the disk is not full. 


1408 Troubleshooting 


Event Code Message Remedy 


300105022 Unable to create anecessary Type: WARN:NIDP:APP:22 


directory for the Image Pool. 
Cause: On startup, the NIDP Image Pool is 


synchronized from eDirectory to the file system. This 
allows HTML pages to access images from a well 
known file system structure. Part of synchronization 
process involves deleting from the file system images 
that no longer exist in eDirectory. Also, the reverse is 
true, images that are new to eDirectory and do not yet 
exist on the file system are created in directories that 
reflect the image set. File system errors may occur 
during this synchronization process if a file or directory 
cannot be deleted or created. 


Action: Make sure the disk is not full. 


300105023 Unable to create anecessary Type: WARN:NIDP:APP:23 


directory for the Image Pool. 
Cause: On startup, the NIDP Image Pool is 


synchronized from eDirectory to the file system. This 
allows HTML pages to access images from a well 
known file system structure. Part of synchronization 
process involves deleting from the file system images 
that no longer exist in eDirectory. Also, the reverse is 
true, images that are new to eDirectory and do not yet 
exist on the file system are created in directories that 
reflect the image set. File system errors may occur 
during this synchronization process if a file or directory 
cannot be deleted or created. 


Action: Make sure the disk is not full. 


300105024 Unable to update the "last Type: WARN:NIDP:APP:24 
used" attribute of an identity 


object. Cause: Each time an identity object is accessed, the 


"last used" time is updated. This allows the system to 
track identities that have not been used for a 
configurable time period so that they may be deleted. 


Action: Make sure the administrator object for the 
Trust/Config data store has rights to the indicated 
directory context. 


300105025 Unable to auto delete an Type: WARN:NIDP:APP:25 


identity object. 
Cause: Periodically, the IDP attempts to clean up 


(delete) identity objects that have not been used for a 
configurable period of time. If an old unused identity is 
found, an attempt will be made to delete it. If that delete 
fails, this error will be logged. 


Action: Make sure the administrator object for the 
Trust/Config data store has rights to the indicated 
directory context. 
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1410 


Event Code 


300105027 


300105028 


300105029 


300105030 


300105031 


300105036 


300106001 


Troubleshooting 


Message 


No Filename specified in 
System property. 


Error trying to delete a 
CardSpace Issued Card 
Identity Object. 


Cannot load a custom LDAP 
Store Plugin module. 


Cannot instantiate a custom 
LDAP Store Plugin module. 


Auser store was configured 
with an unrecognized 
directory type. 


Office365 assertion NamelD 
value is null, check user <user 
name> attribute value. 


Remedy 


Type: WARN:NIDP:APP:27 


Cause: Trying to read properties from file which is not 
specified in System property. 


Action: Make sure the properties file is passed in the 
appropriate system property. 


Type: WARN:NIDP:APP:28 


Cause: When a CardSpace Managed Card that is 
backed by a Personal Card is issued, an Identity object 
is created to represent the "Federation" that allows that 
card to log into the IDP without supplying any additional 
credentials. For security reasons, the user may delete 
that Identity object, or that "federation," when the 
associated card becomes out of date or compromised. 
However, when the system attempted to delete the 
Identity object, the indicated error happened. 


Action: Examine the supplied error detail and take 
applicable actions. 


Type: WARN:NIDP:APP:29 


Cause: The java.lang.Class.forName() method call 
failed to load the LDAP Store Plugin class. 


Action: Ensure a valid Java class file is available in 
Access Manager's class path for the referenced plugin 
class file. 


Type: WARN:NIDP:APP:30 


Cause: The java.lang.Class.newlnstance() method call 
failed to instantiate the LDAP Store Plugin class. 


Action: Ensure a valid Java class file is available in 
Access Manager's class path for the referenced plugin 
class file. Also, ensure the LDAP Store Plugin has a 
zero parameter constructor. 


Type: WARN:NIDP:APP:031 


Cause: The configuration was manually modified to 
include an invalid directory type specifier. Or the 
configuration has been corrupted. Or there was no valid 
implementation of an LDAP Store Plugin for this 
directory type. 


Action: Examine the supplied error detail and take 
applicable actions. 


Cause: User LDAP attribute value is empty in the user 
store. 


Action: Check the user attribute in configured user 
store. If NamelD value is null, check user {1} attribute 
{0} value. 


Type: WARN:NIDP:IDFF:001 


Event Code 


300106002 
300106003 
300106004 
300106005 
500102001 


500102002 


500102003 


500102004 


500102005 


500102006 


Message 


The authentication information 
for the user was successfully 
found. 


The Liberty User Profile object 
for the associated user was 
found in the configuration 
datastore. 


Created new user profile 
object. 


Read data from user profile 
object. 


Attempted to read data from 
the Liberty User Profile object, 
but it did not contain the 
requested data. 


Read data from attributes 
obtained when a remote 
authentication source pushed 
the attributes to the NIDP. 


Remedy 


Type: WARN:NIDP:IDFF:002 
Type: WARN:NIDP:IDFF:003 
Type: WARN:NIDP:IDFF:004 
Type: WARN:NIDP:IDFF:005 
Type: INFO:NIDP:WSF:001 


Scenario: A Web Service request was made to query or 
modify user attributes. The user's authentication 
information was successfully found. 


See Also: 600102001 
Type: INFO:NIDP:WSF:002 


Scenario: A Web Service request was made to query or 
modify user attributes. One of the data locations 
specified for the service is the Liberty User Profile object 
and that object was successfully found. 


Type: INFO:NIDP:WSF:003 


Scenario: A request was made to query or modify user's 
attributes. A Liberty User Profile object did not yet exist 
for this user, So one was created. 


Type: INFO:NIDP:WSF:004 


Scenario: A Web Service request was made to query 
user attributes. One of the data locations specified for 
the service is the Liberty User Profile object and that 
object was successfully read. 


See Also: 600102002 
Type: INFO:NIDP:WSF:005 


Scenario: A Web Service request was made to query 
user attributes. One of the data locations specified for 
the service is the Liberty User Profile object. That object 
was successfully accessed but did not contain the 
requested data. 


Type: INFO:NIDP:WSF:006 


Scenario: When a user authenticates, the authentication 
entity can push user attributes to the NIDP as part of the 
response to the authentication. The NIDP remembers 

these attributes for the life of that user session. If one of 
the data locations specified for a Web Service is remote, 
then these attributes may be returned as part of a query. 


See Also: 600102005 
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Event Code 


500102007 


500102008 


500102009 


500102010 


500102011 


500102012 


500102013 


1412 Troubleshooting 


Message 


Read data by making a call to 
a remote service made 
available through a user 
authentication. 


Completed building composite 
data that was read from all 
data locations for user. 


Initiating a user interaction 
redirect. 


Initiating a user interaction call 
to a trusted user interaction 
service. 


Read Credential Profile data 
from Novell Secret Store. 


Read Credential Profile data 
from an extended user 
authentication object attribute. 


Web service data write denied 
because the LDAP attribute 
plugin access for the named 
data item is read only! 


Remedy 


Type: INFO:NIDP:WSF:007 


Scenario: A request was made to query a user's 
attributes. One of the data locations for the Web Service 
was remote. So, a request was made to a remote 
service to read attributes. 


See Also: 600102006 
Type: INFO:NIDP:WSF:008 


Scenario: A request was made to query a user's 
attributes. If multiple data locations are specified for the 
Web Service, then attributes may be read from multiple 
data locations and then aggregated into a composite 
data structure. 


See Also: 600102007 
Type: INFO:NIDP:WSF:009 


Scenario: A request was made to query or modify user's 
attributes. Policy indicates that the user must be asked if 
the attribute operation is permitted. The request 
indicated that a redirect user interaction service should 
be used to perform user interaction, so redirection is 
being invoked using the redirection user interaction 
service protocol. 


Type: INFO:NIDP:WSF:010 


Scenario: A request was made to query or modify user's 
attributes. Policy indicates that the user must be asked if 
the attribute operation is permitted. The request 
indicated that a trusted user interaction service should 
be used to perform user interaction, so that service is 
being invoked using the trusted user interaction service 
protocol. 


Type: INFO:NIDP:WSF:011 


Scenario: A request was made to query data from a 
user's Credential Profile. The data was successfully 
read. 


See Also: 600102008 
Type: INFO:NIDP:WSF:012 


Scenario: A request was made to query data from a 
user's Credential Profile. The data was read from an 
extended schema attribute on the user's authenticated 
user object. 


See Also: 600102010 
Type: INFO:NIDP:WSF:013 


Scenario: The system administrator has marked this 
data item as read only in the LDAP Attribute Plugin. 


Event Code 


500102014 


500102015 


500103001 


500103002 


500103003 


500103004 


500104002 


500104007 


500104013 


500104014 


Message 


Override not allowed. Cannot 
override existing data. 


Existing data changed since 
notChangedSince time. 


Filled the user attribute 
request from data already in 
the web service consumer 
cache. 


Web service consumer 
request complete. 


Web service consumer 
request requires user 
interaction. 


User interaction policy and 
data values received. 


Getting properties from file 
(informational) 


X509 Authentication matched 
principal (informational) 


No CRL/OCSP defined by the 
administrator 


No CRL/OCSP found in the 
certificate. 


Remedy 


Type: INFO:NIDP:WSF:014 


Scenario: The data that is being written already exists in 
the user's profile. Data override is not allowed so this 
data cannot be written. 


Type: INFO:NIDP:WSF:015 


Scenario: User profile data is marked with the last time 
the data changed. The query request indicated that it 
did not want the data written if the current data in the 
profile has been changed since an indicated time. The 
system determined that the current data in the profile 
has been changed since the time provided, so this data 
cannot be written. 


Type: INFO:NIDP:WSC:001 


Scenario: When the WSC reads user attributes, it 
caches the results of each read. In this case, a 
subsequent request queried attributes already read, so 
they were provided from the WSC cache. 


Type: INFO:NIDP:WSC:002 


Scenario: The WSC was asked to query or modify data 
for a given user. That request is complete. 


Type: INFO:NIDP:WSC:003 


Scenario: The WSC was asked to query or modify data 
for a given user. The entity called to perform the 
operation indicated that the user must be asked if the 
attribute operation is acceptable. 


Type: INFO:NIDP:WSC:004 


Scenario: A Web Service request was made to query or 
modify user attributes. It was determined that the user 
must be asked if the attribute operation is acceptable. 
The user's answers have been returned to the NIDP. 


Type: INFO:NIDP:USERAUTH:002 

Scenario: Getting properties from file 

Type: INFO:NIDP:USERAUTH:007 

Scenario: X509 Authentication matched principal 
Type: INFO:NIDP:USERAUTH:013 

Cause: No CRL/OCSP defined by the administrator 
Type: INFO:NIDP: USERAUTH:014 

Cause: No CRL/OCSP found in the certificate 


Action: CRL/OCSP validations are enabled but no 
CRL/OCSP responder URL was defined by the 
administrator. CRL/OCSP URLs may be defined if 
needed. 
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Event Code 


500104016 


500104048 


500104113 


500105001 


500105002 


500105003 


500105004 


500105005 
500105006 
500105007 
500105008 
500105009 
500105010 
500105011 
500105012 
500105013 
500105014 
500105015 
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Message 


Could not fetch CRL from the 
local cache (informational) 


Successfully loaded NIDP 
PKIX Certificate Path Checker 
Class (informational) 


Kerberos Principal match 
found in the user store 
(informational) 


Forwarding HTTP request to 
cluster member. 


Successfully initialized JNDI 
connections. 


Failed X509 authentication 
due to Login Policy Check 
Extension Method evaluation. 


An recoverable error 
happened while forwarding a 
login request. 


Remedy 


Type: INFO:NIDP:USERAUTH:016 


Scenario: Could not fetch CRL from the local cache, 
getting it from the CDP 


Type: INFO:NIDP:USERAUTH:048 


Scenario: Successfully loaded NIDP PKIX Certificate 
Path Checker Class 


Type: INFO:NIDP:USERAUTH:113 


Scenario: Kerberos Principal found in the user store 


Type: INFO:NIDP:APP:001 


Scenario: A request was received on a cluster member 
that does not own the authentication information for the 
associated user. The request must be processed on the 
cluster member that does own the user authentication 
information, so the request is being forwarded to that 
cluster member. 


Type: INFO:NIDP:APP:002 


Scenario: NIDP attempts to create JNDI connections to 
each user store replica during NIDP startup. In this 
case, NIDP was able to establish connections with the 
indicated host. 


Type: INFO:NIDP:APP:003 


Scenario: The directory login policy for the indicated 
user denied login. 


Type: INFO:NIDP:APP:004 


Scenario: The request landed on the wrong cluster 
member. An attempt was made to proxy the request, but 
an error occurred! However, this ESP can process this 
request, so let execution proceed on this box. 


Type: INFO:NIDP:APP:005 
Type: INFO:NIDP:APP:006 
Type: INFO:NIDP:APP:007 
Type: INFO:NIDP:APP:008 
Type: INFO:NIDP:APP:009 
Type: INFO:NIDP:APP:010 
Type: INFO:NIDP:APP:011 
Type: INFO:NIDP:APP:012 
Type: INFO:NIDP:APP:013 
Type: INFO:NIDP:APP:014 
Type: INFO:NIDP:APP:015 


Event Code Message 
500105016 
500105017 
500105018 
500105019 
500105020 
500105021 
500105022 
500105023 
500105024 
500105025 
500105026 
500105027 
500105028 
500105029 
500105030 
500105031 
500105032 
500105033 
500105034 
500105035 
500105036 
500105037 
500105038 
500105039 
500105040 
500105041 
500105042 
500105043 
500105044 
500105045 


Remedy 


Type 
Type 


Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 
Type: 


: INFO:NIDP:APP:016 
: INFO:NIDP:APP:017 
INFO:NIDP:APP:018 
INFO:NIDP:APP:019 
INFO:NIDP:APP:020 
INFO:NIDP:APP:021 
INFO:NIDP:APP:022 
INFO:NIDP:APP:023 
INFO:NIDP:APP:024 
INFO:NIDP:APP:025 
INFO:NIDP:APP:026 
INFO:NIDP:APP:027 
INFO:NIDP:APP:028 
INFO:NIDP:APP:029 
INFO:NIDP:APP:030 
INFO:NIDP:APP:031 
INFO:NIDP:APP:032 
INFO:NIDP:APP:033 
INFO:NIDP:APP:034 
INFO:NIDP:APP:035 
INFO:NIDP:APP:036 
INFO:NIDP:APP:037 
INFO:NIDP:APP:038 
INFO:NIDP:APP:039 
INFO:NIDP:APP:040 
INFO:NIDP:APP:041 
INFO:NIDP:APP:042 
INFO:NIDP:APP:043 
INFO:NIDP:APP:044 
INFO:NIDP:APP:045 
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Event Code 


500105046 


500106001 
500106002 
500106003 
500106004 
500106005 
500106006 
500106007 
500106008 
600102001 


600102002 


600102003 


600102004 
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Message 


The specified identity object 
was deleted because it was 
not used for a configurable 
time period. 


Verbose user authentication 
information. 


Verbose user authentication 
information, attribute select 
string, and data. 


Read single-valued attribute 
from user authentication 
LDAP object. 


Read multi-valued attribute 
from user authentication 
LDAP object. 


Remedy 


Type: INFO:NIDP:APP:046 


Scenario: Periodically, the IDP attempts to clean up 
(delete) identity objects that have not been used for a 
configurable period of time. If an old unused identity is 
found, an attempt will be made to delete it. When this 
delete succeeds, this message will be logged. 


Type: INFO:NIDP:IDFF:001 
Type: INFO:NIDP:IDFF:002 
Type: INFO:NIDP:IDFF:003 
Type: INFO:NIDP:IDFF:004 
Type: INFO:NIDP:IDFF:005 
Type: INFO:NIDP:IDFF:006 
Type: INFO:NIDP:IDFF:007 
Type: INFO:NIDP:IDFF:008 
Type: DEBUG:NIDP:WSF:001 


Scenario: Adds verbose authentication data to the fact 
that the user associated with the attribute request was 
found in the internal databases of the web service 
provider. 


See Also: 500102001 
Type: DEBUG:NIDP:WSF:002 


Scenario: A Web Service request was made to query 
user attributes. One of the data locations specified for 
the service is the Liberty User Profile object. The data 
listed in this message was successfully read for the 
indicated user using the indicated XPath. 


See Also: 500102004 
Type: DEBUG:NIDP:WSF:003 


Scenario: A Web Service request to query user attribute 
data was received. One of the data locations was LDAP. 
This message displays the value read from the 
indicated LDAP attribute for the indicated user. 


Type: DEBUG:NIDP:WSF:004 


Scenario: A Web Service request to query user attribute 
data was received. One of the data locations was LDAP. 
This message displays the value read from the 
indicated LDAP attribute for the indicated user. 


Event Code 


600102005 


600102006 


600102007 


600102008 


600102009 


600102010 


600105001 


Message 


Verbose user authentication 
and attribute information. 


Adds verbose user and 
attribute information to 
attributes read from a remote 
service whose description was 
obtained at authentication 
time. 


Adds verbose user and 
attribute information to the 
final aggregated result of a 
web service query! 


Adds verbose data to reading 
Credential Profile data from 
Novell Secret Store. 


The user successfully logged 
into Novell Secret Store using 
SAML/SASL. 


Adds verbose data to reading 
Credential Profile data from an 
extended user authentication 

object attribute. 


Do not need to proxy HTTP 
request to other cluster 
member. Well known URL that 
does not require the use of a 


proxy. 


Remedy 


Type: DEBUG:NIDP:WSF:005 


Scenario: When a user authenticates, the authenticating 
entity can push user attributes to the NIDP as part of the 
response to the authentication. The NIDP remembers 

these attributes for the life of that user session. If one of 
the data locations specified for a Web Service is remote, 
then these attributes may be returned as part of a query. 


See Also: 500102006 
Type: DEBUG:NIDP:WSF:006 


Scenario: A request was made to query a user's 
attributes. One of the data locations for the Web Service 
was remote. So, a request was made to a remote 
service to read attributes. 


See Also: 500102007 
Type: DEBUG:NIDP:WSF:007 


Scenario: A request was made to query a user's 
attributes. If multiple data locations are specified for the 
Web Service, then attributes may be read from multiple 
data locations and then aggregated into a composite 
data structure. 


See Also: 500102008 
Type: DEBUG:NIDP:WSF:008 


Scenario: A request was made to query data from a 
user's Credential Profile. The data was successfully 
read. 


See Also: 500102011 
Type: DEBUG:NIDP:WSF:009 


Scenario: To access secrets from Novell Secret Store, 
the user must authenticate to Novell Secret Store. 


Type: DEBUG:NIDP:WSF:010 


Scenario: A request was made to query data from a 
user's Credential Profile. The data was read from an 
extended schema attribute on the user's authenticated 
user object. 


See Also: 500102012 
Type: DEBUG:NIDP:APP:001 


Scenario: The request is one of a well known list of 
request types that may be processed on any cluster 
member, so it does not need to be forwarded to another 
cluster member. 
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Event Code 


600105002 


600105003 


600105004 


600105005 


600105006 


600105007 


600105008 


600105009 
600105010 
600105011 
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Message 


Do not need to proxy HTTP 
request to other cluster 
member. This cluster member 
can handle requests for this 
user. 


Obtained IP address of cluster 
member handling this users 
requests from URL parameter. 


Obtained IP address of cluster 
member handling this users 
requests from HTTP cookie. 


Obtained IP address of cluster 
member handling this user's 
requests by asking cluster 
members which one handles 
this user session. 


Must proxy HTTP request to 
other cluster member. 


Response of proxy HTTP 
request. 


Successfully obtained SOAP 
response document. 


Remedy 


Type: DEBUG:NIDP:APP:002 


Scenario: The request arrived at the cluster member 
that owns the authentication information for the user. 
The request may have come straight from the router to 
this cluster member, or the request may have been 
forwarded here by another cluster member. 


Type: DEBUG:NIDP:APP:003 


Scenario: Each request must be processed on the 
cluster member that owns the user authentication 
information. The IP address of that cluster member was 
found in a URL parameter. 


Type: DEBUG:NIDP:APP:004 


Scenario: Each request must be processed on the 
cluster member that owns the user authentication 
information. The IP address of that cluster member was 
found in an HTTP cookie. 


Type: DEBUG:NIDP:APP:005 


Scenario: Each request must be processed on the 
cluster member that owns the user authentication 
information. The IP address of that cluster member was 
found by asking all cluster members which one knew 
about the user's session. 


Type: DEBUG:NIDP:APP:006 


Scenario: Each request must be processed on the 
cluster member that owns the user authentication 
information. It has been determined that this cluster 
member is not the correct cluster member to process 
this request, so the request must be forwarded to 
another cluster member. 


Type: DEBUG:NIDP:APP:007 


Scenario: Each request must be processed on the 
cluster member that owns the user authentication 
information. It was determined that this cluster member 
is not the correct cluster member to process this 
request, so the request was forwarded to another 
cluster member. The results of the request, as 
processed on the other cluster member, are displayed 
here. 


Type: DEBUG:NIDP:APP:008 


Scenario: A SOAP request was made and a response 
was expected, the response was successfully obtained. 


Type:DEBUG:NIDP:APP:009 
Type: DEBUG:NIDP:APP:010 
Type: DEBUG:NIDP:APP:011 


30.18.3 


Event Code Message Remedy 


200104401 Login failed. Please try again. Rule group is not associated to Risk-Based 
authentication class. Map a rule group to the class. 


200104403 Authentication failed. Authentication failed. The geolocation rule is enabled 
but the geolocation provider is not configured or is 
configured incorrectly. 


500104400 Access denied. Contact your User is denied login because the risk score is high. 
administrator 


500104402 Access denied. Contact your No risk level is defined for this risk score. 
administrator 


200104067 The target domain is Cause: URL is not configured as a whitelist domain or it 
unknown. Contact your is invalid. 


administrator. 
Action: If the URL is valid and required, contact the 


administrator to get it configured in the redirection 
whitelist. 


Linux Access Gateway Appliance(045) 


Component 045 
Event Code Description Remedy 
[1-9]04501000 Multi-homing See the string value in the message 
for a description of the cause. 
[1-9]04502000 Service manager See the string value in the message 
for a description of the cause. 
[1-9]04503000 Browser request processing See the string value in the message 
for a description of the cause. 
[1-9]04504000 Authentication processing See the string value in the message 
for a description of the cause. 
[1-9]04505000 Authorization processing See the string value in the message 
for a description of the cause. 
[1-9]04506000 Identity Injection processing See the string value in the message 
for a description of the cause. 
[1-9]04507000 Form Fill processing See the string value in the message 
for a description of the cause. 
[1-9]04508000 Caching See the string value in the message 
for a description of the cause. 
[1-9]04509000 Processing of Web server responses and of See the string value in the message 
responses to browser requests for a description of the cause. 
[1-9]04511000 Rewriter processing See the string value in the message 
for a description of the cause. 
[1-9]04512000 SOAP back channel processing See the string value in the message 


for a description of the cause. 
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Event Code 


[1-9]04513000 


[1-9]04514000 


[1-9]04515000 


[1-9]04516000 


[1-9]04517000 


[1-9]04518000 


[1-9]04519000 


[1-9]04520000 


[1-9]04521000 


[1-9]04522000 


Description Remedy 


Device communication channel (VCC) See the string value in the message 
for a description of the cause. 


VM controller processing See the string value in the message 
for a description of the cause. 


Connection management See the string value in the message 
for a description of the cause. 


Core utilities (VXE) See the string value in the message 
for a description of the cause. 


Data Stream processing See the string value in the message 
for a description of the cause. 


SSL processing See the string value in the message 
for a description of the cause. 


Command processing See the string value in the message 
for a description of the cause. 


Profiler See the string value in the message 
for a description of the cause. 


Proxy start See the string value in the message 
for a description of the cause. 


Audit event processing See the string value in the message 
for a description of the cause. 


30.18.4 Access Gateway Service (046) 


Component 046 


+ 


+ 


+ 


+ 


Subgroup 00: 
Subgroup 01: 
Subgroup 02: 
Subgroup 03: 
Subgroup 30: 
Subgroup 50: 
Subgroup 51: 
Subgroup 52: 
Subgroup 53: 
Subgroup 54: 
Subgroup 55: 


Event Code 


URL Request Processing 

Authorization Processing 

Identity Injection Processing 

Form Fill Processing 

Web Server Communication Processing 
Administration Request Processing 
Statistics 

Health 

Alerts Processing 

Configuration Processing 


Initialization- Termination Processing 


Description Remedy 


URL Request Processing (00) 
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Event Code 


304600404 


504600000 


504600100 


504600400 
504600401 


504600402 


504600403 


504600405 


604600001 
604600002 


604600003 
604600301 


604600302 
604600303 
604600304 


604600306 


604600307 
604600308 


604600309 


604600310 


604600311 


Description 


Authentication Request: Unknown 
Contract 


URL Accessed 


Protected Resource Accessed 


Authentication Request: Successful 


Login Request: Redirect To ESP 


Authentication Request: Set Cookie 


Authentication Request: Redirect URL 


with Cookie 


Authentication Request: NRL Request 


URL Accessed: Trace Summary 


URL Accessed: Scheme Redirect 


URL Accessed: Pinned 


Session Broker: Cookie Not Found 


Session Broker: Add User 
Session Broker: Get Cookie 


Session Broker: Delete User 


Session Broker: Update User 


Session Broker: Cookie Found 


Session Broker: Add User SOAP 
Request 


Session Broker: User Added 


Session Broker: Delete User 
Successful 


Session Broker: Delete User Failed 


Remedy 


Cause: An unknown contract was received 
from the Embedded Service Provider. This can 
happen if the configuration of Identity Server 
and Access Gateway are not synchronized. 


Action: Check to see if Access Gateway or 
Identity Server need to be updated. If their 
status is current, make a small change to both 
and update their configuration. 


Arequest for access to an unprotected URL 
has been received. 


A request for access to a protected URL has 
been received. 


The user authenticated successfully. 


The authentication request was redirected to 
the Embedded Service Provider 


The request has been redirected to set the 
cookie. 


The original URL request has been redirected 
to the Embedded Service Provider with a 
cookie. 


The protected resource is configured for non- 
redirected login. 


This event accesses the URL trace summary. 


The URL accessed on wrong scheme is 
redirected. 


The URL in the PIN list is accessed. 


The session broker returns the status of cokkie 
not found. 


The session broker requests to add user. 
The session broker requests cookie. 


The session broker deletes user sent from 
SOAP request. 


The session broker updates the user sent from 
SOAP request. 


The session broker returned requested cookie. 


The session broker adds the user sent from 
SOAP request. 


The session broker adds user request which 
are successfully processed. 


The session broker deletes the user 
successfully. 


The session broker failed to delete user. 
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Event Code Description 


Authorization Processing (01) 


204601102 Policy Configuration Reply: Policy Error 


204601302 Policy Evaluation Reply: Policy Error 


504601003 ACL Policy Configuration Request 


504601100 Policy Configuration Reply: Success 


504601203 Policy Evaluation Request 


504601300 Policy Configuration Reply: Access 
allowed, no match 


504601301 Policy Configuration Reply: Access 
allowed 


504601302 Policy Configuration Reply: Access 
denied 


Identity Injection Processing (02) 


204602102 Policy Configuration Reply: Policy Error 


204602302 Policy Evaluation Reply: Policy Error 


504602100 Policy Configuration Reply: Success 


504602300 Policy Evaluation Reply: Inject 
Authentication Header 


504602301 Policy Evaluation Reply: Inject Custom 
Headers 


504602302 Policy Evaluation Reply: Inject Query 
Parameters 


Form Fill Processing (03) 


204603101 Policy Configuration Reply: No Policy 
ID 
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Remedy 


Cause: An error was detected while 
processing a policy configuration request. 


Action: Check the health of the configuration 
database. If it is unhealthy, repair it or restore it 
from a backup. 


Cause: An error was detected while 
processing a policy evaluation request. 


Action: Verify that the Embedded Service 
Provider and the proxy service are running. 


ACL configuration request is being processed. 


The Authorization policy has been configured 
successfully. 


A policy evaluation request has been received; 
the evaluation has started. 


The Authorization policy evaluation results 
allowed access due to policy default action. 


The Authorization policy evaluation results 
allowed access. 


The Authorization policy evaluation results 
denied access. 


Cause: An error was detected while 
processing a policy configuration request. 


Action: Check the health of the configuration 
database. If it is unhealthy, repair it or restore it 
from a backup. 


Cause: An error was detected while 
processing a policy evaluation request. 


Action: Verify that the Embedded Service 
Provider and the proxy service are running. 


The Identity Injection policy has been 


configured successfully. 


This policy injects an authentication header 


This policy injects custom headers. 


This policy injects query parameters. 


The policy ID is not included with policy 
configuration request. 


Event Code 


204603102 


204603302 


204603304 


504603100 


504603300 
504603301 
504603400 
504603401 


Description 


Policy Configuration Reply: Policy Error 


Policy Evaluation Reply: Policy Error 


Policy Evaluation Reply: Parse Error: 


Unknown field 


Policy Configuration Reply: Success 


Policy Evaluation Reply: Success 
Policy Evaluation Reply: No Policy 
Get User Attributes 


Set User Attributes 


Administration Request Processing (50) 


204650002 
504650002 
604650002 
704650002 
204650003 


204650005 
504650005 
604650005 
704650005 
204650001 
504650001 
604650001 
704650001 
304650004 
604650004 
504650010 


DCC Message Processing 


JCC 


Device Information Requests 


Command Processing 


Service Information Requests 


Start 


Remedy 


Cause: An error was detected while 
processing a policy configuration request. 


Action: Check the health of the configuration 
database. If it is unhealthy, repair it or restore it 
from a backup. 


Cause: An error was detected while 
processing a policy evaluation request. 


Action: Verify that the Embedded Service 
Provider and the proxy service are running. 


Cause: A parsing error was detected while 
processing a policy evaluation request. 


Action: Check the Form Fill policy and make 
sure it matches the form. 


The Form Fill policy has been configured 
successfully. 


The Form Fill policy evaluation was successful. 
The Form Fill policy was not found. 
A request has been sent to get user attributes. 


A request has been sent to set user attributes. 


These events will processes the DCC 
messages. 


The information is related to sending and 
processing JCC requests. 


These events will process the request of the 
device information. 


Administration Console initiates the log events 
pertaining to processing commands. 


The service information requests are 
processed. 


The log events pertaining to a Start command 
received from Administration Console. 
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Event Code 


504650011 


504650012 


504650013 


504650014 


504650015 


Statistics (51) 
204651001 
304651001 
504651001 
604651001 
704651001 
504651000 


Health (52) 
204652001 
304652001 
604652001 
704652001 
504652000 


Description Remedy 


Stop The log events pertaining to a Stop command 
received from Administration Console. 


Restart The log events pertaining to a Restart 
command received from Administration 
Console. 


Refresh Policy The log events pertaining to a Refresh Policy 
command received from Administration 
Console. 


Cache Clear The log events pertaining to a Cache Clear 
command received from Administration 
Console. 


IP Scan The log events pertaining to an IP Scan 
command received from Administration 
Console. 


Statistics Request Processing The log events pertaining to the processing of 
a Statistics request from device manager. 


Statistics The log of current statistics requested by 
device manager. 


Health Request Processing The log events pertaining to the processing of 


a health request from device manager. 


Health The log of current health as requested by 
device manager. 


30.18.5 Server Communications (JCC) (007) 


Component 007 


+ 


+ 


+ 


+ 


+ 


Subgroup 01: 
Subgroup 02: 
Subgroup 03: 
Subgroup 04: 
Subgroup 05: 
Subgroup 06: 
Subgroup 07: 
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Package com.novell.jcc.cert 
Package com.novell.jcc.client 
Package com.novell.jcc.handler 
Package com.novell.jcc.proxy 
Package com.novell.jcc.schedule 
Package com.novell.jcc.server 


Package com.novell.jcc.servlet 


¢ Subgroup 08: Package com.novell.jcc.sockets 


¢ Subgroup 09: Package com.novell.jcc.util 


Event 
Code 


100701002 


100701003 


100701004 


100701005 


100701006 


100701007 


100701008 


100701009 


Description 


Cannot interpret PKCS12 data for 
CertCommand 


Set key entry failed on [store name] 


KeyStoreException - set certificate entry 
failed 


KeyStoreException - delete entry failed 


Exception - key usage extension failed 


Exception - get alternate name extension 
failed 


Keystorelnfo class has not been initialized 


[key file] is missing required information 
for keystore named [keystore name] 


Remedy 


Cause: The PKCS12 package was corrupted in 
transit or contained a certificate with a 
unsupported level encryption for the Java 
security provider (such as 4096 bit support). 


Action: Verify that you are using a supported 
certificate size and try the operation again. 


Cause: The Java keystore password became 
out of sync with the admin server, or an IO error 
occurred. 


Action: Try operation again, otherwise submit 
the app_sc.@.log and jcc-@.1og.60 files for 
resolution. 


Cause: The Java keystore password became 
out of sync with the admin server, or an IO error 
occurred. 


Action: Try operation again, otherwise submit 
the app_sc.0.log and jcc-0.1og.0 files for 
resolution. 


Cause: A keystore entry for the specified alias 
does not exist. 


Action: Verify the previous key import 
commands were successful. Otherwise, submit 
the app_sc.0.log and jcc-0.1og.0 files for 
resolution. 


Cause: The key usage extension specified by 
Administration Console was invalid. 


Action: Submit the app_sc.0.1log and jcc- 
©.10g.0 files for resolution. 


Cause: Alternate name format specified by 
Administration Console was invalid. 


Action: Submit the app_sc.0.log and jcc- 
©.1og.0 files for resolution. 


Cause: Likely a previous error occurred during 
keystore initialization. 


Action: Submit the jcc-0.1og.0 file for 
resolution. 


Cause: The keystore information supplied at 
installation is missing or corrupt. 


Action: Reinstall. Otherwise submit the jcc- 
©.1lo0g.0 file for resolution. 
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Event 
Code 


100701010 


100701011 


100701012 


100701013 


100701014 


100701015 


100702001 


100702002 


100702003 


1426 Troubleshooting 


Description 


[key file] is missing 


Exception - close keystore (persisting) 
failed 


Exception - eDirectory keystore 
initialization failed 


Exception - Java keystore initialization 
failed 


Exception PKCS12 keystore initialization 


failed 


Exception - loading keystore failed 


Package com.novell.jcc.client 


Exception sending alert 


Could not create default response XML 


Exception while building alert request: 
[exception], retrying 


Remedy 


Cause: The keystore information supplied at 
installation is missing or corrupt. 


Action: Uninstall and reinstall the server 
component. Otherwise submit the jcc- 
©.10g.0 file for resolution. 


Cause: Could not write the key to the keystore. 


Action: Try the operation again. Otherwise, 
submit the jcc-@.1og.0 file for resolution. 


Cause: Could not connect to the config store. 
Action: Restart the server. 


Cause: The password to the keystore was 
incorrect, or the keystore file could not be 
opened. 


Action: Verify the keystore exists, and try the 
operation again. Otherwise, submit the jcc- 
©.10g.0 file for resolution. 


Cause: The password to the PKCS12 key was 
incorrect. 


Action: Submit the jcc-0.1og.0 file for 
resolution. 


Cause: The encrypted keystore_info.xml file 
could not be read. 


Action: Reinstall the server component. 
Otherwise, submit the jcc-0.1log.90 file for 
resolution. 


Cause: Alert could not be sent to the 
Administration Console. 


Action: Make sure the server can 
communicate with Administration Console. 
Otherwise, submit the jcc-0. log. © file for 
resolution. 


Cause: A problem occurred creating the 
default XML document. 


Action: Submit the jcc-0.10g.0 file for 
resolution. 


Cause: The alert information was not saved in 
XML correctly. 


Action: Submit the jcc-0.1log.0 file for 
resolution. 


Event Description Remedy 
Code 


100702004 Configuration for Device Manager not set Cause: The settings file determining where to 
send the alert was not found. 


Action: Restart the novell-jcc service. 
Otherwise, submit the jcc-0.1log.90 file for 


resolution. 
100702005 Error getting configuration for Device Cause: There was a problem reading the 
Manager settings file. 


Action: Restart the novell-jcc service. 
Otherwise, submit the jcc-0.1log.90 file for 
resolution. 


100702006 Alert could not be sent Cause: The response from Administration 
Console was not successful. 


Action: The system will try indefinitely to 
resend the alert. Make sure Administration 
Console is functioning. Otherwise, submit the 
jcc-0.1log.0 file for resolution. 


100702007 Bad health URL Cause: The IP address or port setting for 
Administration Console has been corrupted. 


Action: Make sure the settings.properties file 
contains correct information. Restart the novell- 
jcc service. 


100702008 Error sending alert Cause: The system cannot communicate with 
Administration Console. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


100702009 Error sending alert Cause: The system cannot communicate with 
Administration Console, or some other 
communication error occurred. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


100702010 Exception - connection disconnect failed Cause: An error occurred with reading the alert 
response or a disconnect error occurred. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


100702011 Queued alerts cannot be saved Cause: The class structure has likely changed 
or the alertdispatch.dat file could not be 
created. 


Action: The error is non-fatal, continue running 
service. 
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Event 
Code 


100702012 


100702013 


100702014 


100702015 


100702016 


100702017 


100702018 


100702019 


100702020 


1428 Troubleshooting 


Description 


Queued alerts cannot be restored 


Exception - setting keystore or trust store 
failed 


Exception getting health from [service 


name] 


Exception creating health XML 


MalformedURLException - Bad health 


URL 


Error sending periodic health 


Error sending periodic health 


Crypto key not found 


Error calling initializationComplete/ 
serviceStopComplete 


Remedy 


Cause: The code has likely changed or the 
alertdispatch.dat file could not be read. 


Action: The error is non-fatal, continue running 
service. 


Cause: The keystore_info.xml file was corrupt 
or does not exist. 


Action: Reinstall the server component. 
Otherwise, submit the jcc-0.1log.90 file for 
resolution. 


Cause: Could not communicate to obtain the 
health from named component. 


Action: Restart the service. Otherwise, submit 
the jcc-0.1o0g.0 file for resolution. 


Cause: A problem occurred reading health 
data while creating the health XML. 


Action: The operation will retry. If it persists, 
submit the jcc-@.1og.0 file for resolution. 


Cause: The IP address or port setting for 
Administration Console has been corrupted. 


Action: Make sure the settings.properties file 
contains correct information. Restart the novell- 
jcc service. 


Cause: The system cannot communicate with 
Administration Console. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


Cause: The system cannot communicate with 
Administration Console, or some other 
communication error occurred. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


Cause: The jcc.keystore file was not found. 


Action: Make sure the installation completed 
successfully, and that the novell-jcc service is 
running. Otherwise, submit the jcc-0.log.0 
file for resolution. 


Cause: An RMI error occurred communicating 
with the novell-jcc service. 


Action: Make sure the installation completed 
successfully, and that the novell-jcc service is 
running. Otherwise, submit the jcc-0.log.0 
file for resolution. 


Event Description Remedy 
Code 


100702021 Server is not connected Cause: The novell-jcc service is not running. 


Action: Make sure the installation completed 
successfully, and that the novell-jcc service is 
running. Otherwise, submit the jcc-0.1log.0 
file for resolution. 


100702022 Error binding to RMI port Cause: The novell-jcc service is not running, or 
the RMI ports are already bound by some other 
process. 


Action: Make sure the installation completed 
successfully, and that the novell-jcc service is 
running. Otherwise, submit the jcc-0.log.0 
file for resolution. 


100702023 Error registering with server Cause: The component could not register with 
the novell-jcc service. Likely and RMI 
communication error. 


Action: Restart the novell-jcc service. If the 
problem persists, submit the jcc-0.1og.0 file 
for resolution. 


100702024 Cannot contact server; retrying Cause: The novell-jcc service was stopped, 
likely temporarily. 


Action: Make sure that the novell-jcc service is 
running. Otherwise, restart it. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


100702025 Error sending alert to server Cause: An RMI communication error likely 
occurred while sending an alert to the novell-jcc 
service. 


Action: Make sure that the novell-jcc service is 
running. Otherwise, restart it. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


100702026 Queued alerts cannot be saved Cause: 


An RMI communication error likely occurred 
while saving alerts through the novell-jcc 
service. 


Action: 


Make sure that the novell-jcc service is running. 
Otherwise, restart it. If the problem persists, 
submit the jcc-@.1og.0 file for resolution. 


100702027 Queued alerts cannot be restored Cause: The [name]-alerts.dat file was 
corrupted. 


Action: The error is non-fatal, but monitor the 
file system for further problems. 


Package com.novell.jcc.handler 
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Event 
Code 


100703001 


100703002 


100703003 


100703004 


100703005 


100703006 


100703007 


100703009 


100703010 


1430 Troubleshooting 


Description 


Exception - Response creation failed 


Exception - Response creation failed 


Error executing command: response is 


null 


Bad URL from Device Manager 


"+responseURL+ 


Command error 


Command response error, retry # 


Major or minor version not supplied 
[version] 


Content-Length header [total] and actual 
data length [read] mismatch 


Could not connect to [URL] 


Remedy 


Cause: A problem occurred creating the 
default XML document. 


Action: Submit the jcc-0.1log.90 file for 
resolution. 


Cause: The default response information was 
not saved in XML correctly. 


Action: Submit the jcc-0.1log.0 file for 
resolution. 


Cause: Command response from a server 
component was not set. 


Action: Submit the jcc-0.1log.90 file for 
resolution. 


Cause: The URL given by the administration 
server was incorrect. 


Action: Submit the jcc-0.log.0 and 
app_sc.0.1og files from the admin console for 
resolution. 


Cause: The protocol used in response to the 
command was malformed. 


Action: Submit the jcc-0.1log.0 file for 
resolution. 


Cause: Administration Console is likely 
temporarily down or restarting. 


Action: Allow for retry to occur. If all retries fail, 
ensure that Administration Console is up and 
functioning. 


Cause: A server component did not supply the 
required version information. 


Action: Submit the jcc-0.1log.90 file for 
resolution. 


Cause: The data read did not match the 
expected length. 


Action: Restart the server component. If the 
problem persists, submit the jcc-0.1og.0 file 
for resolution. 


Cause: Could not communicate with 
Administration Console or the server 
component. 


Action: Make sure the system can 
communicate with Administration Console and 
is operating. If the URL is 127.0.0.1, restart the 
server component. 


Event Description Remedy 
Code 


100703011 Exception - stats response creation failed Cause: Could not convert stats XML to be sent 
to Administration Console. 


Action: Submit the jcc-0.1log.0 file for 


resolution. 
100703012 Exception - version response creation Cause: Could not convert version XML to be 
failed sent to Administration Console. 


Action: Submit the jcc-0.1og.0 file for 
resolution. 


Package com.novell.jcc.proxy 


100704001 Exception - Cipher socket create key Cause: Could not create socket cipher key. 


failed f , 
Action: Submit the jcc-0.log. 0 file for 


resolution. 


100704002 AGProxy has not initialized as client is null Cause: The proxy subcomponent is not 
initialized. 


Action: Restart the novell-jcc service. 
Otherwise, submit the jcc-0. log. © file for 


resolution. 
100704003 Command returned: [response code] Cause: Access Gateway is processing a 
[response message], Retry # previous command. 


Action: Allow the retry to occur. If it persists, 
restart the server. 


100704004 Error sending [name] command Cause: Could not send the command to 
Access Gateway. 


Action: If the problem persists, restart the 
server. Otherwise submit the jcc-0. log. © file 
for resolution. 


100704005 Could not send alert Cause: A problem occurred while sending 
alert. 


Action: This is a non-fatal error. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


100704006 Exception - update password failed Cause: Could not read the config user 
password. 


Action: Restart the server. Otherwise, submit 
the jcc-0.1og.90 file for resolution. 


100704007  ecc.cfg does not exist! Cause: A problem during the installation 
process occurred. 


Action: Submit the jcc-0.1o0g.0 file for 
resolution, then reinstall the server. 


100704008 Error loading ecc.cfg Cause: Could not read the ecc .cfg file. 


Action: Allow the operation to retry, otherwise, 
submit the jcc-0.1og.90 file for resolution. 
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Event 
Code 


100704009 


100704010 


100704011 


100704012 


100704013 


100704014 


100704015 


100704016 


100704017 


100704018 


1432 Troubleshooting 


Description 


Stopped waiting for JCC server 


Cannot write ecc.cfg 


Error reading configuration 


Cannot write ecc.cfg 


Exception - check esp status failed 


Error reading password 


Exception - Cipher socket create key 
failed 


Load settings failed 


LAGProxy has not initialized as client is 
null 


Could not send alert 


Remedy 


Cause: The server didn't initialize in a timely 
manner. 


Action: Restart the novell-jcc service. 
Cause: Could not write the specified config file. 


Action: Allow the operation to retry. If it 
persists, restart the server. 


Cause: Could not parse Access Gateway 
configuration data. 


Action: Allow the operation to retry. If it 
persists, submit the jcc-0.10g.0 file for 
resolution and restart the server. 


Cause: Could not write specified file. 


Action: Allow the operation to retry. If it 
persists, submit the jcc-0.10g.0 file for 
resolution and restart the server. 


Cause: An RMI error occurred while 
communicating to the ESP component. 


Action: Allow the operation to retry. If it 
persists, submit the jcc-0.10g.0 file for 
resolution and restart the server. 


Cause: Could not read the config user 
password. 


Action: Restart the server. Otherwise, submit 
the jcc-0.1og.0 file for resolution. 


Cause: Could not create socket cipher key. 


Action: Submit the jcc-0.1log.0 file for 
resolution. 


Cause: The settings could not be loaded for 
Linux AG. 


Action: Restart the novell-jcc service. 
Otherwise, submit the jcc-0.1log.90 file for 
resolution. 


Cause: The proxy subcomponent is not 
initialized. 


Action: Restart the novell-jcc service. 
Otherwise, submit the jcc-0.1log.90 file for 
resolution. 


Cause: An error occurred while sending an 
alert. 


Action: This is a non-fatal error. If it persists, 
restart the novell-jcc service. 


Event 
Code 


100704019 


100704020 


100704021 


100704022 


100704024 


100704025 


100705001 


100705002 


100705003 


Description 


Stopped waiting for JCC server 


Error reading configuration 


Exception - setting VCC ID failed 


Linux Proxy is not running 


Exception - Cipher socket create key 
failed 


Stopped waiting for JCC server 


Package com.novell.jcc.schedule 


Error getting client details 


Error getting client details 


Exception getting stats from [name] 


Remedy 


Cause: The server didn't initialize in a timely 
manner. 


Action: Restart the novell-jcc service. 


Cause: Could not parse Access Gateway 
configuration data. 


Action: Allow the operation to retry. If it 
persists, submit the jcc-0.10g.0 file for 
resolution and restart the server. 


Cause: Could not write the config. xml file 
with the original ID. 


Action: This error would occur during the re- 
import process. Click Repair Import on 
Administration Console to resolve. Otherwise, 
submit jcc-0.1log.0 file for resolution. 


Cause: The proxy novell-vmc service has 
stopped responding. 


Action: to restart the proxy service, enter the 
following command as root user: 


/etc/init.d/novell-vmc restart 
Cause: Could not create socket cipher key. 


Action: Submit the jcc-@.1o0g.0 file for 
resolution. 


Cause: The server didn't initialize in a timely 
manner. 


Action: Restart the novell-jcc service. 


Cause: An RMI communication error likely 
occurred. 


Action: Allow the system to retry the operation. 
If it persists, submit the jcc-0.1log.0 file for 
resolution. 


Cause: An RMI communication error likely 
occurred. 


Action: Allow the system to retry the operation. 
If it persists, submit the jcc-0.1log.0 file for 
resolution. 


Cause: The periodic statistics subsystem was 
not able to get the stats from the server 
component. 


Action: Make sure the component is running. If 
it persists, restart the component. 
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Event 
Code 


100705004 


100705005 


100705006 


100705007 


100705008 


100706001 


100706002 


100706003 


1434 Troubleshooting 


Description 


Exception creating stats XML 


Bad stats URL 


Error sending periodic stats 


Error sending periodic stats 


Error sending statistics 


Package com.novell.jcc.server 


[service name] not registered 


[service name] not found in registry 


Client list cannot be saved 


Remedy 


Cause: An error occurred while creating 
statistics XML data. 


Action: Submit the jcc-0.1log.90 file for 
resolution. 


Cause: The IP address or port setting for 
Administration Console has been corrupted. 


Action: Make sure the settings.properties file 
contains correct information. Restart the novell- 
jcc service. 


Cause: The system cannot communicate with 
Administration Console. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


Cause: The system cannot communicate with 
Administration Console, or some other 
communication error occurred. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


Cause: The system cannot communicate with 
Administration Console, or some other 
communication error occurred. 


Action: Make sure the system can 
communicate with Administration Console and 
that it is functioning properly. 


Cause: The server component was already 
disconnected. 


Action: This is a non-fatal error. 


Cause: The specified server component was 
not found so it could not be unregistered. 


Action: This is a non-fatal error. 


Cause: An IO error occurred while saving the 
list of registered server components. 


Action: Make sure the file has write access. If 
the problem persists, submit the jcc-0.1log.0 
file for resolution. 


Event Description Remedy 
Code 


100706004 Client list cannot be restored Cause: An IO error occurred while reading the 
list of registered server components. 


Action: Make sure the file has read access. If 
an upgrade has been performed, make sure all 
components on the system have also been 
upgraded. If the problem persists, submit the 
jcc-0.1og.90 file for resolution. 


100706005 Could not stop connector Cause: The embedded HTTP server could not 
be stopped. 


Action: Allow the system to retry the operation. 
If it persists, submit the jcc-@.10g.0 file for 
resolution. 


100706006 No HTTP connectors were added Cause: An internal software problem occurred. 


Action: Submit the jcc-0.1og.0 file for 
resolution. 


100706007 Exception - setting keystore properties on Cause: The keystore_info. xml file could 
http connector failed not be read, or was corrupted. 


Action: Submit the jcc-0.1og.0 file for 
resolution. Reinstall if necessary. 


100706008 Could not start HTTP server. Retry Cause: Some other application may be using 
Number: [n] the port we require to be open. 


Action: Allow the system to retry the operation. 
If it persists, submit the jcc-@.10g.0 file for 
resolution. 


100706009 Exception during jcc shutdown Cause: A problem shutting down the 
embedded HTTP server occurred. 


Action: This is a non-fatal error. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


100706010 Exception in testing HTTP server Cause: An error testing the HTTP server 
occurred. 


Action: This is a non-fatal error. 


100706011 MalformedURLException- HTTP server Cause: An error testing the HTTP server 
occurred. 


Action: This is a non-fatal error. 


100706012 Failed to load eDirectory keystore Cause: Service could not register handler into 
provider keystore Java environment handler set. 


Action: This is a non-fatal error. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 
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Event 
Code 


100706013 


100706014 


100706015 


100706016 


100706017 


100706018 


100706019 


100706020 


100706021 


100706022 


1436 Troubleshooting 


Description 


Missing keystore information file: [key 
information file]. Certificate Management 
functions are unavailable 


Exception - command failed 


Exception - cert command failed 


Error during execution 


Exception - delete info failed 


JCC Server startup failed 


Embedded HTTP Server already started 


Error starting embedded tomcat 


RMI problem 


RMI exception 


Remedy 


Cause: An install-time problem occurred where 
the keystore information file was not created, or 
was deleted after installation. 


Action: Submit the jcc-0.1og.0 file for 
resolution. 


Cause: The post-keystore update command 
failed. 


Action: Try the operation again. Otherwise, 
submit the jcc-@.1og.0 file for resolution. 


Cause: A certificate operation was 
unsuccessful. 


Action: Try the operation again. Otherwise, 
submit the jcc-@.1og.0 file for resolution. 


Cause: The external command did not execute 
properly. 


Action: Try the operation again. Otherwise, 
submit the jcc-@.1og.0 file for resolution. 


Cause: A problem occurred deleting internal 
information. 


Action: This is a non-fatal error. 


Cause: A critical error occurred during the 
startup of the novell-jcc service. 


Action: To restart the novell-jcc service, enter 
the following command: 


/etc/init.d/novell-jcc restart 


If the problem persists, submit the jcc- 
©.10g.0 file for resolution. 


Cause: The internal HTTP server was already 
started when asked to start. 


Action: This is a non-fatal error. 


Cause: Another process is likely using the 
novell-jcc service port (default 1443). 


Action: Make sure there are no other 
processes using this port, then restart the 
service. 


Cause: An error occurred during the shutdown 
process. 


Action: This is a non-fatal error. 


Cause: An error occurred during the shutdown 
process. 


Action: This is a non-fatal error. 


Event Description Remedy 
Code 


100706023 Server did not initialize within 60 seconds Cause: A server component initialization 
message could not be completed as the novell- 
jcc service is not finished initializing. 


Action: To restart the novell-jcc service, enter 
the following command: 


/etc/init.d/novell-jcc restart 


If the problem persists, submit the jcc- 
©.10g.0 file for resolution. 


100706024 Exception - JCC server initialization failed Cause: A server component initialization 
message could not be completed. 


Action: To restart the novell-jcc service, enter 
the following command: 


/etc/init.d/novell-jcc restart 


If the problem persists, submit the jcc- 
©.10g.0 file for resolution. 


100706025 Error binding to RMI [port] Cause: Another process is likely using the 
novell-jcc service port (default 1197). 


Action: Make sure there are no other 
processes using this port, then restart the 
service. 


100706026 Error registering remote object Cause: A problem occurred during the RMI 
bind process. 


Action: Make sure that all components are of 
the same build of Access Manager. Then 
restart novell-jcc service. 


100706027 Error sending alert Cause: A problem occurred sending the import 
command to Administration Console. 


Action: Allow the system to retry the operation. 
If it persists, submit the jcc-0.1log.0 file for 
resolution. 


100706028 Error getting client details for import Cause: An RMI communication error has 
occurred between the server component and 
the novell-jcc service. 


Action: Make sure the server component is 
functioning properly and try the operation 
again. If the problem persists, submit the jcc- 
©.1log.0 file for resolution. 


100706029 Error sending alert command Cause: Problem sending a command-type alert 
to Administration Console. 


Action: Make sure Administration Console is 
running. Allow the system to retry the 
operation. If it persists, submit the jcc- 
©.1lo0g.0 file for resolution. 
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1438 


Event Description 
Code 


100706030 Exception - get keystore information failed 


100706031 Error getting key [key name] to [key file] 


100706032 Could not get keystore information for 
reimport of [Service name] 


100706033 Exception 


100706034 Exception - get key failed 


100706035 RMI exception during execution of 
[command name] 


Troubleshooting 


Remedy 


Cause: A problem occurred sending the 
keystore information from the 
keystore_info.xml file. 


Action: If the server shows up in 
Administration Console, click Repair Import. 
Otherwise, submit jcc-0.1log.0 and 
app_sc.0.1og files for resolution. 


Cause: A problem occurred receiving the 
assigned keys during a reimport operation. 


Action: Ensure Administration Console is 
operational, perform the steps to re-trigger an 
auto-import. Otherwise, submit the jcc- 
©.1log.0 and app_sc.0.1og files for 
resolution. 


Cause: A problem occurred receiving the 
assigned keystore information during a 
reimport operation. 


Action: Ensure the admin console is 
operational, perform the steps to re-trigger an 
auto-import. Otherwise, submit the jcc- 
©.1log.0 and app_sc.0.1og files for 
resolution. 


Cause: A problem occurred during a reimport 
operation. 


Action: Ensure the admin console is 
operational, perform the steps to re-trigger an 
auto-import. Otherwise, submit the jcc- 
©.1log.0 and app_sc.0.1og files for 
resolution. 


Cause: An assigned key could not be obtained 
during a reimport operation. 


Action: Allow the operation to retry. Ensure the 
admin console is operational, perform the steps 
to re-trigger an auto-import. Otherwise, submit 
the jcc-@.log.0 and app_sc.@.1og files for 
resolution. 


Cause: An RMI communication error occurred 
while executing a command from 
Administration Console. 


Action: Try the operation again. If the problem 
persists, submit the jcc-0.1o0g.0 file for 
resolution. 


Event 
Code 


100706036 


100706037 


100706038 


100706039 


100706040 


100706041 


100706042 


100707001 


Description 


RMI exception 


Error collecting health from [service name] 


Error collecting stats from [service name] 


RMI exception 


RMI exception 


RMI exception 


RMI exception 


Package com.novell.jcc.servliet 


Servlet error in [handler name] 


Remedy 


Cause: An RMI communication error occurred 
while executing a command from 
Administration Console. 


Action: Try the operation again. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


Cause: An RMI communication error occurred 
while obtaining the health information from a 
server component. 


Action: Allow the operation to try again. Make 
sure the server component is running properly. 
If the problem persists, submit the jcc- 
©.1lo0g.0 file for resolution. 


Cause: An RMI communication error occurred 
while obtaining the stats information from a 
server component. 


Action: Allow the operation to try again. Make 
sure the server component is running properly. 
If the problem persists, submit the jcc- 
©.1log.0 file for resolution. 


Cause: A communication error occurred. 


Action: Make sure the server component is 
running properly. If the problem persists, submit 
the jcc-0.1log.90 file for resolution. 


Cause: A communication error occurred. 


Action: Make sure the server component is 
running properly. If the problem persists, submit 
the jcc-0.1log.90 file for resolution. 


Cause: A communication error occurred. 


Action: Make sure the server component is 
running properly. If the problem persists, submit 
the jcc-0.1og.90 file for resolution. 


Cause: A communication error occurred. 


Action: Make sure the server component is 
running properly. If the problem persists, submit 
the jcc-0.1og.90 file for resolution. 


Cause: An error occurred responding to a 
administration console request. 


Action: Try the operation again. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 
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Event 
Code 


100707002 


100707003 


100707004 


100707005 


100707006 


100708001 


100708002 


100708003 


1440 Troubleshooting 


Description 


IO error in [handler name] 


No client found with ID [service name] 


[appliance id] header missing from [IP 
address] 


No handler is registered for [query string] 


Exception registering handler 


Package com.novell.jcc.sockets 


Could not initialize the cipher 


Could not initialize the cipher 


Error creating socket factory 


Remedy 


Cause: An IO error occurred while responding 
to a administration console request. 


Action: Try the operation again. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


Cause: The specified server component known 
to Administration Console is not currently 
running, or cannot communicate with the 
novell-jcc service. 


Action: Make sure the server component is 
running properly. Ensure all components on the 
system are of the same version and build. 
Restart the server component. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


Cause: An invalid request was submitted to the 
novell-jcc service. 


Action: This is likely an un-authorized login 
attempt. Locate the remote IP address and 
follow proper security procedures. 


Cause: An invalid request was submitted to the 
novell-jcc service. 


Action: This is likely an un-authorized login 
attempt. Locate the remote IP address and 
follow proper security procedures. 


Cause: A problem occurred during start up of 
the novell-jcc service. 


Action: Make sure the jcc/webapps/jcc/ 
WEB-INF/web.xm1 file is not corrupt. 


Cause: The cipher could not be initialized. 
Action: Try restarting the novell-jcc service. 
Cause: The cipher could not be initialized. 
Action: Try restarting the novell-jcc service. 


Cause: A possible security problem has been 
attempted, or the jcc. keystore file is corrupt. 


Action: Check the jcc. keystore timestamp 
of last the modification, and if it is different than 
install-time, you might have a security problem. 


Event Description Remedy 
Code 


100708004 Could not find keystore_info.xml Cause: The install process did not complete 
successfully. 


Action :Restart the novell-jcc service. 
Otherwise, submit the jcc-0.1log.0 file for 
resolution and reinstall the server component. 


Package com.novell.jcc.util 


100709001 Error saving settings Cause: An IO error occurred while saving 
install-time settings. 


Action: Submit the jcc-0.1o0g.0 file for 
resolution and reinstall the server component. 


100709002 Error loading settings Cause: An IO error occurred while reading 
install-time settings. 


Action: Submit the jcc-0.1log.0 file for 
resolution and reinstall the server component. 


100709003 Error creating JCC key Cause: A critical error occurred while creating 
the certificate for communicating with the 
administration server. 


Action: Submit the jcc-0.1log.0 file for 
resolution and reinstall the server component. 


100709004 Error saving settings Cause: An IO error occurred while saving 
install-time settings. 


Action: Submit the jcc-0.10g.0 file for 
resolution and reinstall the server component. 


100709005 Exception - install trusted roots failed Cause: A communication error occurred while 
sending trusted roots to the administration 
server. 


Action: Ensure the admin console is running 
properly. Otherwise, submit the jcc-0.log.0 
file for resolution and reinstall the server 
component. 


100709006 Could not get keys Cause: The default keys could not be obtained 
from the administration server. 


Action: Allow the system to retry the operation. 
If the problem persists, make sure the admin 
console is operational. Otherwise, submit the 
jcc-0.log.0 and app_sc.0.1og files for 
resolution. 


100709007 Error getting esp ID Cause: The server component install likely 
terminated before completion. 


Action: Reinstall server component. 


100709008 Exception - configure LAG failed Cause: A problem occurred while setting up 
keystore information for Access Gateway. 


Action: Reinstall the server. 
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Event 
Code 


100709009 


100709010 


100709011 


100709012 


100709013 


100709014 


100709015 


100709016 


100709017 


100709018 
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Description 


Could not get admin name/password from 
NW 


Could not create keystores 


Exception - get key failed 


Exception - Cert not valid 


Exception - Cert not valid 


Error creating key 


Exception during configuration 


Could not open [jcc log file] 


[path]/settings.properties file does not 
exist 


No remote management address is set. 


Remedy 


Cause: An install-time error occurred during 
the CD-install process. 


Action: Reinstall the server. 


Cause: An error occurred while creating the 
keystore information during the configuration 
process. 


Action: Reinstall the server component. 


Cause: The default key could not be obtained 
from Administration Console during the initial 
configuration. 


Action: Ensure Administration Console is 
operational, and reinstall the server component. 


Cause: The default trusted root obtained from 
Administration Console is not yet valid. 


Action: Make sure the system time and time 
zone matches that of Administration Console, 
then reinstall. 


Cause: The default trusted root obtained from 
Administration Console is not yet valid. 


Action: Make sure the system time and time 
zone matches that of Administration Console, 
then reinstall. 


Cause: A critical error occurred writing the 
jcc.keystore file. 


Action: Submit the jcc-0.1og.0 file for 
resolution, reinstall the server component. 


Cause: A fatal problem occurred during 
installation. 


Action: Submit the jcc-0.1log.0 file for 
resolution, reinstall the server component. 


Cause: Make sure the installation succeeded. 


Action: Restart the server. If the problem 
persists, submit the jcc-0.10g.0 file for 
resolution. 


Cause: An install-time error occurred. 


Action: Submit the jcc-0.1log.0 file for 
resolution, reinstall the server component. 


Cause: An IP address has not been specified 
for Administration Console. 


Action: On the server command-line, set an 
administration console IP address. 


Event Description Remedy 
Code 


100709019 JCC server certificate was not found in: Cause: An install-time error occurred. 


[keystore file] ; 
Action: Submit the jcc-0.1log.0 file for 


resolution, reinstall the server component. 


100709020 Exception reading keystore information Cause: The keystore_info. xml file is 
missing, or corrupt. Or, the internal keystore 
has been tampered with, or the certificate is 
expired. 


Action: Submit the jcc-0.1log.0 file for 
resolution, reinstall the server component. 


100709021 Exception - get JCC keystore information Cause: The keystore_info. xml file is 
failed missing, or corrupt. 


Action: Submit the jcc-0.1log.0 file for 
resolution, reinstall the server component. 


100709022 — IllegalArgumentException Cause: An internal component made an invalid 
call. 


Action: Submit the jcc-0.1log.90 file for 
resolution. 


100709023  IllegalStateException Cause: An internal component made an invalid 
call. 


Action: Submit the jcc-0.1log.0 file for 
resolution. 


100709024 Object could not be saved Cause: A system setting file cannot be saved. 


Action: Submit the jcc-0.1log.0 file for 
resolution. 


100709025 Object cannot be restored Cause: A system setting file cannot be 
restored. 


Action: Submit the jcc-0.1log.90 file for 
resolution. 


30.18.6 Policy Engine (008) 


Component 008 


¢ Subgroup 01: Engine 

¢ Subgroup 02: Condition Handler 

¢ Subgroup 03: Action Handler 

¢ Subgroup 04: Configure Information Context 
¢ Subgroup 05: Information Context 

+ Subgroup 06: Response Context 


* = any Sub group 
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Event 


Description 


Code 


100801001 
100802001 
100803001 
100804001 
100805001 
100806001 
200801002 
200802002 
200803002 
200804002 
200805002 
200806002 


200801003 
200802003 
200803003 
200804003 
200805003 
200806003 
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Error No Memory: Memory allocation 
failed. 


Error Bad Data: Policy configuration 
contains an invalid policy parameter list 
enumerative value. 


Error Configuration. The policy 
configuration is syntactically incorrect or 
malformed. 


Remedy 


Cause: Low system memory. Resource 
allocation failed. 


Action: Determine cause for low system 
memory and resolve. 


Cause: Administration Console has produced 
an invalid policy configuration document. 


Cause: Policy configuration document has 
been corrupted. 


Action: Take any or all of the following actions: 


1. Submit the log file to Novell Support to aid 
in determining and fixing the source of the 
problem. 


2. Back up to a previously working policy 
configuration until the problem has been 
fixed. 


3. Examine the policy configuration 
document (available in PEP trace entries) 
to determine the erroneous policy 
document element and remove the 
corresponding policy statement from your 
policy configuration until a fix for the 
problem is available. 


Cause: Administration Console has produced 
an invalid policy configuration document. 


Cause: Policy configuration document has 
been corrupted. 


Action: Take any or all of the following actions: 


1. Submit the log file to Novell Support to aid 
in determining and fixing the source of the 
problem. 


2. Back up to a previously working policy 
configuration until the problem has been 
fixed. 


3. Examine the policy configuration 
document (available in PEP trace entries) 
to determine the erroneous policy 
document element and remove the 
corresponding policy statement from your 
policy configuration until a fix for the 
problem is available. 


Event 
Code 


200801004 
200802004 
200803004 
200804004 
200805004 
200806004 
200801072 
200802072 
200803072 
200804072 
200805072 
200806072 


200801073 
200802073 
200803073 
200804073 
200805073 
200806073 
200801074 
200802074 
200803074 
200804074 
200805074 
200806074 


Description 


General Failure: Internal software error. 


Interface Unavailable: Invalid 
InformationContext or ResponseContext 
enumerative value. 


Data Unavailable: Policy Engine could not 
obtain needed information to complete 
policy evaluation. 


Illegal State: Policy Engine caught 
NullPtrException during policy 
configuration or evaluation. 


Remedy 


Cause: Unexpected exception caught during 
policy evaluation. 


Action: Submit log file to Novell Support for 
analysis and problem resolution. 


Cause: Administration Console has produced 
an invalid policy configuration document. 


Invalid PolicyTypeSpec schema. 


Cause: Policy configuration document has 
been corrupted. 


Action: Take any or all of the following actions: 


1. Submit the log file to Novell Support to aid 
in determining and fixing the source of the 
problem. 


2. Back up to a previously working policy 
configuration until the problem has been 
fixed. 


3. Examine the policy configuration 
document (available in PEP trace entries) 
to determine the erroneous policy 
document element and remove the 
corresponding policy statement from your 
policy configuration until a fix for the 
problem is available. 


Cause: Inaccessible user store or database. 


Action: Ensure user store or database is 
available. 


Cause: Network connectivity problems. 


Action: Ensure network is operational. 


Cause: Unexpected software exceptions. 


Action: Submit log to Novell Support for 
analysis and resolution. 
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Event Description Remedy 
Code 


200801075 Illegal Argument: Internal software error. | Cause: Invalid method argument received. 

200802075 Action: Submit log to Novell Support for 
analysis and resolution. 

200803075 

200804075 

200805075 

200806075 

300801071 Evaluation Canceled: Active policy Cause: May occur during system shutdown. 


evaluation canceled. 
300802071 Action: If not caused by system shutdown, 


submit log to Novell Support for analysis and 


300803071 resolution. 


300804071 
300805071 
300806071 
500801000 Success: Policy operation completed Cause: Policy Evaluation. 

without error. 
500802000 Action: No Action. Informational only. 
500803000 
500804000 
500805000 
500806000 
500801005 Operation Pending: Policy operation isin Cause: Policy Evaluation. 

progress 
500802005 Action: No Action. Informational only. 
500803005 
500804005 
500805005 
500806005 
500803064 Permit Action: Policy evaluation rendered Cause: Permit action executed. 

a Permit Action. 

Action: No Action. Informational only. 

500803065 Deny Action: Policy evaluation rendered a Cause: Deny action executed. 

Deny Action. 

Action: No Action. Informational only. 

500803066 Obligation Action: Policy evaluation Cause: Obligation action executed. 


rendered an Obligation Action. 
Action: No Action. Informational only. 
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30.18.7 


Event 


Description 


Code 


500801067 


No Action: Policy evaluation rendered no 


Remedy 


Cause: No action was executed during a policy 


500802067 
500803067 
500804067 
500805067 
500806067 
500802068 


500802069 


200802070 


Action. 


Condition False: Policy condition returned 
FALSE. 


Condition True: Policy condition returned 
TRUE. 


Condition Unknown. Policy configuration 
contains an unsupported condition 
handler definition. 


evaluation. 


Action: No Action. Informational only. 


Cause: Policy Evaluation. 
Action: No Action. Informational only. 
Cause: Policy Evaluation. 
Action: No Action. Informational only. 


Cause: Administration Console has produced 
an invalid policy configuration document. 


Cause: Policy configuration document has 
been corrupted. 


Action: Take any or all of the following actions: 


1. Submit the log file to Novell Support to aid 
in determining and fixing the source of the 
problem. 


2. Back up to a previously working policy 
configuration until the problem has been 
fixed. 


3. Examine the policy configuration 
document (available in PEP trace entries) 
to determine the erroneous policy 
document element and remove the 
corresponding policy statement from your 
policy configuration until a fix for the 
problem is available. 


SOAP Policy Enforcement Point (011) 


The SOAP Policy Enforcement Point (PEP) interface is used by the NetWare and Access Gateways 
for policy evaluation. 


Component 011 


¢ Subgroup 01: General/Configuration 
¢ Subgroup 02: Authorization PEP 

¢ Subgroup 03: Identity Injection PEP 
¢ Subgroup 04: Form Fill PEP 


Messages are logged to the catalina.out for trace and application level logging when Identity Server 
logging is enabled. 
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Event Code Description 


General/Configuration 


501101010 Start Policy Soap Handler 


501101011 Stop Policy Soap Handler 


101101012 Policy Evaluator Not Running 


101101013 General Failure 


501101020 Request Received 


501101021 Response Sent 


101101022 Unsupported request received 
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Remedy 


Policy Soap Message Handler received 
start command. 


Cause: Embedded Service Provider has 
been started 


Action: None. Informational message only. 


Policy Soap Message Handler received 
stop command. 


Cause: Embedded Service Provider has 
been stopped 


Action: None. Informational message only. 
The Policy Evaluator has been stopped. 


Cause: The Embedded Service Provider 
has been stopped by an administrator 


Action: Restart the Embedded Service 
Provider for the device. 


General failure processing policy request. 


Cause: Most often caused by incorrectly 
formatted XML. 


Action: Check catalina.out for stack trace 
and possibly more detailed information 
regarding the failure. 


Soap request received. 


Cause: Informational message which logs 
the type of request received 


Action: None. Informational message used 
for checking soap handler interactions. 


Soap response sent. 


Cause: Informational message regarding 
soap response to a request 


Action: None. Informational message used 
for checking soap handler interactions. 


A NXPES command other than configure, 
evaluate or terminate was received. 


Cause: The policy engine revision is 
incompatible with the application. 


Action: Validate the software installation. 


Event Code 


201101023 


501101030 


201101030 


101101031 


501101032 


501101040 


Description 


Unrecognized Policy Identifier 


Configure Success 


Configure Warning 


Configure Failure 


Configure - Empty Policy Set 


Terminating policy 


Remedy 


Policy evaluation was requested for an 
unknown policy. 


Cause: The policy identifier known to 
Access Gateway is stale. 


Action: Most often, this problem is detected 
by Access Gateway and the policies are 
reconfigured. If the problem persists, send 
an Apply or Apply Changes to the device 
from the CLI or Administrative Console. 


Successful policy configuration. 
Cause: Policy configuration succeeded 


Action: None. Informational message used 
for checking policy configuration. 


Policy Configuration Warning. 


Cause: Policy configuration request 
reported a problem in retrieving 
configuration data from the config store 


Action: Check the policy definitions in 
Administration Console to ensure the 
configuration store is working properly, then 
reapply the configuration to the device. 


The policy requested is malformed or 
causes an exception during the 
configuration process. 


Cause: This is accompanied with a 
possible reason for the failure. 


Action: Check the policy configuration in 
the administrative console and reapply the 
configuration to the device. 


The set of policies requested either do not 
apply to the policy enforcement point or the 
set of policies do not match the categories 
selected in the policy enforcement list. 


Cause: This may be normal operation. 


Action: If a policy is expected, check the 
category of the policy and make sure the 
policy is enabled for the device. 


The set of policies represented by the policy 
ID are no longer needed and will be 
removed from the operating policy set. 


Cause: This happens each time a 
configuration is applied to the device. 


Action: None. This is an informational 
message only. 
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Event Code 


501101050 


501101051 


501101052 


501101053 
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Description 


Evaluating policy 


Policy Evaluation - Invalid User Error 


Policy Evaluation - Information Query Error 


Policy Evaluation - WSC Query Error 


Remedy 


An evaluation request has been received 
for the set of policies represented by the 
policy ID. 


Cause: This happens at least once per user 
session per configured policy enforcement 
point. 


Action: None. This is an informational 
message only. 


User session received for policy evaluation 
was not found or contains invalid data. 


Cause: The Identity Service Provider which 
authenticated the user is not accessible 
from the Embedded Service Provider. 


Action: Most often, this error will 
automatically restart the user identification 
process for Access Gateway. 


If that does not occur: 


Administrator: If problem persists, check 
health status of Identity Service Provider 
and take appropriate action. 


End User: Retry request. If not redirected 
to the Identity Service Provider, force a 
refresh of the current browser page and 
Access Gateway/Embedded Service 
Provider will reinitiate the authentication 
process. 


The Policy Evaluator is unable to gain 
access to information required by the policy. 


Cause: This is accompanied with a 
possible reason for failure. 


Action: As the administrator, check the 
health status of Identity Service Provider 
and take appropriate action. 


An attempt to use the WSC query 
mechanism of the ESP failed, the requested 
policy data is unavailable. 


Cause: This is accompanied with a 
possible reason for failure. 


Action: As the administrator, check the 
health status of Identity Service Provider 
and take appropriate action. 


Event Code Description 


501101054 Policy Evaluation - Cluster Data Query 
Error 
501101055 Policy Evaluation - Cluster Query Retry 


Count 


Authorization PEP 


501102050 Policy Evaluation Trace 


Identity Injection PEP 


501103050 Policy Evaluation Trace 
Form Fill PEP 
501104050 Policy Evaluation Trace 


Remedy 


Attempt to retrieve user session data from 
ESP cluster member failed. 


Cause: The Embedded Service Provider 
which authenticated the user may not be 
accessible from the Embedded Service 
Provider evaluating the policy. 


Action: Most often, this error will 
automatically restart the user identification 
process for Access Gateway. 


If that does not occur: 


End User: Close browser and retry 
request. 


Administrator: Check the health status of 
Embedded Service Provider referenced by 
IP address in the log and take appropriate 
action. 


Informational message containing the 
number of retries the ESP has made to 
request policy information from another 
cluster member. 


Cause: The Embedded Service Provider 
which authenticated the user may not be 
accessible from the Embedded Service 
Provider evaluating the policy. 


Action: None, this is an informational 
message only. 


Trace of an individual policy evaluation. 
Cause: Policy evaluation. 


Action: None. Informational message used 
for checking policy evaluation. 


Trace of an individual policy evaluation. 
Cause: Policy evaluation. 


Action: None. Informational message used 
for checking policy evaluation. 


Trace of an individual policy evaluation. 
Cause: Policy evaluation. 


Action: None. Informational message used 
for checking policy evaluation. 
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30.18.8 Backup and Restore (010) 


1452 


Backup and restore are invoked by script files: 


¢ defbkparm.sh: Created by install. This has the default values for the scripts. 


¢ getparams.sh: Prompts administrator for information needed to do the backup or restore 
operation. 


¢ ambkup.sh: Script to run to perform a backup. 
¢ amrestore.sh: Script to run to perform a restore. 
Other programs used by backup and restore: 
¢ ICE: This is the eDirectory utility to import and export LDIF file in and out of eDirectory. 


¢ IdifReverse: This is a program that reverses the order of the records in the LDIF file exported 
from eDirectory. Reversing the order of records allows the LDIF file to be imported without errors. 


¢ certtool.jar: This is a eDirectory certificate utility that backs up and restores the CA key, server 
keys, and trusted roots to a zip file. 


Component 010 
¢ Subgroup 01: Backup 


¢ Subgroup 02: Restore 
¢ Subgroup 03: certtool (certificate backup and restore) 


Messages are logged to the ambkup.log file. 


Event Code Description Remedy 


Backup 


201001001 Backup failed to export data Cause: The ICE utility failed to export directory 
from the configuration store. information to an LDIF file. 


Action: Make sure that ICE is in the proper location 
(Linux: /opt/novell/eDirectory/bin). 


Action: Make sure that the host IP address, port, 
administrator, password are all correct. 


Action: Make sure the back up file is writable 


201001002 Backup failed to format data for Cause: The IdifReverse utility failed to sort the LDIF 
a successful restore. records. 


Action: Make sure that IdifReverse is in the proper 
location (Same directory as backup command). 


Action: Make sure the back up file is writable 


Action: Check for the backup file you specified with 
"_pre" appended to the file name. 


If the file exists, run the following command: 
ldifReverse bkupfile_pre bkupfile 


Replace bkupfile with the filename you specified for 
the backup file. It should create bkupfile which is the 
desired back up file. 
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Event Code Description 


201001003 


201002001 


201002002 


201002003 


201002004 


201002005 


201002006 


Backup failed to export 
certificates to the backup zip 
file. 


Restore 


Backup file does not exist. 


Backup file does not appear to 
be valid. 


Restore failed to access the 
configuration store. 


Restore failed to format the 


current configuration store data. 


Restore failed to prepare the 
configuration store for data 
import. 


Restore failed to prepare the 
configuration store for data 
import. 


Remedy 


Cause: The certtool utility failed to export the certificates 
to a zip file. 


Action: Make sure that certtool. jar is in the proper 
location (Same directory as backup command). 


Action: Make sure the back up file is writable. 
Action: Manually export the certificates to a zip file: 


java -Djava.library.path=/opt/novell/lib -jar 
certtool.jar -edirTree your_tree -edirIP 
000.000.000.000 -edirServer 
cn=!ServerName.@=novell -edirUser 
cn=admin.o=novell -edirPwd secret -bkup -file 
ServerName _20060828_0930.zip -pwd certsecret 
-trcontainer trustedRoots.access 
ManagerContainer.novell -caName "your_tree CA" 


Cause: The backup file does not exist. The name of the 
backup file specified in answer to the prompt should not 
include the final the .ldif or .zip extension. 


Action: Specify the correct name of the back up file. 


Cause: An simple analysis of the backup file indicates 
that the LDIF file specified backup file (with . 1ldif 
appended to the name) is not a valid backup file. 


Action: Make sure to specify a backup file that was 
created by the Access Manager Backup utility. 


Cause: The ICE utility failed to access the eDirectory 
configuration store. 


Action: Make sure that ICE is in the proper location 
(Linux: /opt/novell/eDirectory/bin). Make sure 
that the host IP address, port, administrator, password 
are all correct. 


Cause: Restore was not able to save a current copy of 
the configuration store. A current copy of the config store 
is saved before the import in case the import fails. 


Action: Make sure that IdifReverse is in the proper 
location (Same directory as backup command). 


Cause: ICE failed. Unknown reason because it has 
previously been invoked successfully in the restore 
script. 


Cause: ICE failed. Unknown reason because it has 
previously been invoked successfully in the restore 
script. 
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Event Code Description 


101002007 Restore failed to restore the 
backup data. 


101002008 Failed to restore certificate from 
backup file. 


101002009 Failed to reconfigure VCDN 
user objects. 


certtool utility 


201003002 IP address is missing. 


201003005 eDirectory user id missing. 
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Remedy 


Cause: ICE failed. Unknown reason because it has 
previously been invoked successfully in the restore 
script. 


Action: Check the configuration store for the following 
container: 


ou=accessManagerContainer, o=novell 


If it is not there, locate the recover .ldif file. It should 
be in the directory where you ran the restore command. 
Run ICE to recover the configuration store to the state it 
was in before you attempted the restore. Enter the 
following command: 


/opt/novell/eDirectory/bin/ice -SLDIF -f 
recover.ldif -C -n -DLDAP -SXXX.XXX.XXX.XXX - 
p636 -k -dcn=admin, o=novell -wadmin_password 
-F 


Cause: The java program restores the certificate failed. 
The java program is certtool.jar which provides 
command line access to various eDirectory certificate 
functions. 


Action: See the log file (ambkup . 10g) for more specific 
details. The log file contains a listing of relevant 
parameters with each error message. Assuming the 
back up from which you are trying to restore was 
successful, failure to restore is probably an incorrectly 
supplied parameter. Enter the following command: 


JAVA -classpath vcdnbkup.jar:cert tool.jar 
com.novell.nids.bkuputil. Util -userid 
cn=admin, o=novell -pwd secret -vcdnUser 


Cause: The VCDN user objects were not restored with 
their passwords. Device Manager will not start up until 
the passwords have been properly set. 


Action: This is accompanied with an error x01004xxx. 
Please refer to that error. 


Cause: The certtool.jar was launched without the -edirlP 
option. A script file might have been incorrectly modified. 


Action: Make sure the -edirlP option is specified in the 
script when it launches the certtool utility. 


Cause: The certtool.jar was launched without the - 
eDirUser option. A script file might have been incorrectly 
modified. 


Action: Make sure the -edirUser cn=admin.o=novell 
option is specified in the script when it launches the 
certtool utility. 


Event Code Description 


201003006 


201003009 


201003011 


201003013 


201003040 


201003041 


201003042 


201003043 


301003044 


201003045 


eDirectory user password 
missing. 


File name missing. 


Encryption password missing. 


Name of trusted root container 
missing. 


Failed to open backup file for 
writing. 


Failed to retrieve certificate 
names from eDirectory. 


Failed to retrieve certificate 
xxxx from eDirectory. 


Failed to write certificate xxxx to 
backup file. 


Error closing backup. 


Failed to write trusted root xxxx 
to backup file. 


Remedy 


Cause: The certtool.jar was launched without the - 
edirPwd option. A script file may have been incorrectly 
modified. 


Action: Make sure the -edirPwd option is specified in 
the script when it launches the certtool utility. 


Cause: The certtool.jar was launched without the -file 
(name of backup file) option. A script file may have been 
incorrectly modified. 


Action: Make sure the -file option is specified in the 
script when it launches the certtool utility. 


Cause: The certtool.jar was launched without the -pwd 
option. A script file may have been incorrectly modified. 


Action: Make sure the -pwd option is specified in the 
script when it launches the certtool utility. 


Cause: The certtool.jar was launched without the - 
trContainer (trusted root container) option. A script file 
may have been incorrectly modified. 


Action: Make sure the -trcontainer option is specified in 
the script when it launches the certtool utility. 


Cause: Backup was unable to create or access the 
backup file in which to save certificate information. 


Action: Ensure that user running backup sufficient 
rights. 


Cause: A PKI or eDirectory error. 


Action: This error will be accompanied by an error 
string. 


Cause: The certtool failed to retrieve the certificate 
identified in the error. Problems have been seen trying to 
export certificate with pending CSRs. 


Action: This error will be accompanied by an error 
string. 


Cause: The certificate identified in the error message 
did not get saved to the backup file. 


Action: An exception string included in the message my 
provide additional information. 


Cause: Likely will not cause a problem. 


Action: Try extracting the contents of the zip file created 
by backup to verify the integrity of the zip file. 


Cause: The trusted root identified in error messages did 
not get saved to the backup file. 


Action: An exception string included in the message 
might provide additional information. 
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Event Code Description 


201003046 


201003048 


201003049 


201003050 


201003051 


201003052 


301003053 


201003056 


201003057 


201003058 
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Failed to retrieve trusted root 
xxxx from eDirectory. 


Not all items were backed up. 


Failed to retrieve the CA xxxx 
from eDirectory. Likely a PKI or 
eDirectory error. 


Failed to write CA key xxxx to 
backup file. 


Failed to open backup file for 
reading. 


Not all items were restored. 


Error closing backup. 


Error importing CA key: xxxx 


Error importing key: xxxx 


Error importing trusted root: 
XXXX 


VCDN configuration 


Remedy 


Cause: The certtool failed to retrieve the trusted root 
identified in the error. Likely a PKI or eDirectory error. 


Action: This error will be accompanied by an error 
string. 


Cause: See accompanying errors. 


Action: Refer to previous error messages to identify 
which certificates or trusted roots were not backed up. 


Cause: The certtool failed to retrieve the CA key 
identified in the error. 


Action: This error will be accompanied by an error 
string. 


Cause: The CA key identified in the error did not get 
written to the backup file. 


Action: An exception string included in the message my 
provide additional information. 


Action: Make sure the backup file exists. Do not include 
.ldif or .zip in the name of the back up file. 


Action: Make sure the user logged in has sufficient 
rights to access the file. 


Cause: See accompanying errors. 


Action: Refer to previous error messages to identify 
which certificates or trusted roots were not backed up. 


Action: This error occurred after all restore operations 
had completed. Should not cause any problem. 


Action: The CA key was not restored. See the 
accompanying Error for more information. Likely a PKI 
error. 


Action: Make sure the password you provided matches 
the encryption password used when backing up the data. 


Cause: The CA key was not restored. See the 
accompanying Error for more information. Likely a PKI 
error. 


Action: Make sure the password you provided matches 
the encryption password used when backing up the data. 


Cause: The trusted root was not restored. See the 
accompanying Error for more information. Likely a PKI 
error. 


30.18.9 


Event Code Description Remedy 


201004001 Failed to configure VCDN The VCDN user objects were not restored with their 
objects for data store access. | passwords. Device Manager will not start up until the 
passwords have been properly set. 


Cause: The vcdnbkup.jar utility failed to reset 
passwords for VCDN objects. This causes errors starting 
up device manager. 


Action: Make sure /opt/volera/roma/conf/ 
vcdn.conf file is present and has the correct 
information. 


To fix enter the following command in the /opt/novell/ 
devman/bin directory: 


java -jar vcdnbkup.jar -userid 
cn=admin, o=novell -pwd admin_password - 
vcdnuUser 


201004002 Application Error. The VCDN user objects were not restored with their 
passwords. Device Manager will not start up until the 
passwords have been properly set. Accompanied by a 
stack trace with more information. 


Cause: vcdnbkup.jar utility failed to reset passwords for 
VCDN objects. This will cause errors starting up device 
manager. 


Action: Make sure the information in /opt/volera/ 
roma/conf/vcdn.conf file is correct: 


Fix the file by running the following command (in /opt/ 
novell/devman/bin): 


java -jar vcdnbkup.jar -userid 


cn=admin, o=novell -pwd admin_password - 
vcdnUser 


Modular Authentication Class (012) 


The Modular Authentication Service (NMAS) Class provides access to a number of advanced 
authentication mechanisms available from NetIQ and NetIQ partners. 


Component 012 
¢ Subgroup 01: General/Configuration 
¢ Log file: catalina.out for trace and application level logging as enabled by the log settings (click 
Identity Server > Edit > Logging) 
Event Code Description Remedy 


General/Configuration 
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Event Code 


301201001 


101201002 


101201003 


101201004 


501201005 


101201006 


101201007 
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Description 


NMAS Authentication Class 


NMAS Authentication Class 


NMAS Authentication Class 


NMAS Authentication Class 


NMAS Authentication Class 


NMAS Authentication Class 


NMAS Authentication Class 


Remedy 


The log message language resource file could 
not be located. 


Cause: The log message language resource 
file was not found 


Action: Verify installation. 
Error getting LDAP host address. 
Cause: System configuration. 


Action: Verify installation and availability of 
LDAP host server. 


The NMAS_LOGIN_SEQUENCE initialization 
property were not provided. 


Cause: The NUAS_LOGIN_ SEQUENCE 
property was not defined for the authentication 
class. 


Action: Use the management interface to add 
the NUAS_LOGIN_SEQUENCE property to 
either the class or the method, and assign it 
the name of a valid NMAS login sequence. 


Unable to write to HTTPResponse 
Cause: Unknown 

Action: Check system status. 
UserID not found. 

Cause: Invalid User ID. 

Action: Verify username 

Invalid NMAS Login state. 
Cause: Unknown 

Action: Check server status. 
NMAS Login Error. 

Cause: See NMAS Error codes. 


Action: Indicated by NMAS error code. 


VV Appendix 


The following sections contain additional documentation and information about Access Manager: 


+ Appendix A, “Data Model Extension XML,” on page 1461 

+ Appendix B, “SOAP versus REST API,” on page 1467 

+ Appendix C, “OAuth versus Other Protocols,” on page 1469 

+ Appendix D, “Access Manager Reports Samples,” on page 1471 
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Data Model Extension XML 


The data model for some Web services is extensible. You can enter XML definitions of data model 
extensions in a custom profile (for more information, see “Modifying Service and Profile Details for 
Employee, Custom, and Personal Profiles” on page 518). Data model extensions hook into the 
existing Web service data model at predefined locations. 


All schema model extensions reside inside of a schema model extension group. The group exists to 
bind model data items together under a single localized group name and description. Schema model 
extension groups can reside inside of a schema model extension root or inside of a schema model 
extension. There can only be one group per root or extension. Each root is hooked into the existing 
Web service data model. Multiple roots can be hooked into the same location in the existing Web 
service data model. This conceptual model applies to the structure of the XML that is required to 
define data model extensions. 


The high-level view of the data model extension XML is as follows: 


<SchemaExtensions> 
<Root> 
<Group> 
<Extension> 
<Group> 
<Extension>...</Extension> 
<Extension>...</Extension> 
</Group> 
</Extension> 
<Extension> 
<ValueSet> 
<Value/> 
<Value/> 
</ValueSet> 
</Extension> 
</Group> 
<Root> 
<Root>...</Root> 


</SchemaExtensions> 


Elements 


The definition of the attributes for each data model extension XML element are as follows: 


+ “Root Element” on page 1462 

e “Group Element” on page 1462 

+ “Extension Element” on page 1462 
e “ValueSet Element” on page 1463 
e “Value Element” on page 1464 
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Root Element 


parent: The unique identifier of the “hook point” in the Web service’s data model. These hook points 
are defined by the Web service data model schema. These unique identifiers represent the xpaths of 
each data item within the model schema. Possible values for the parent attribute are listed in Table A- 
qe 


Table A-1 Root Element 


Personal Profile /pp:PP/pp:Extension 
/pp:PP/pp:CommonName/pp:Extension 
/pp:PP/pp:CommonName/pp:AnalyzedName/pp:Extension 
/pp:PP/pp:Legalldentity/pp:Extension 
/pp:PP/pp:Legalldentity/pp: VAT/pp:Extension 
/pp:PP/pp:Legalldentity/pp:AltID/pp:Extension 
/pp:PP/pp:Employmentidentity/pp:Extension 
/pp:PP/pp:AddressCard/pp:Extension 
/pp:PP/pp:AddressCard/pp:Address/pp:Extension 
/pp:PP/pp:MsgContact/pp:Extension 
/pp:PP/pp:Facade/pp:Extension 
/pp:PP/pp:Demographics/pp:Extension 


Employee Profile /ep:EP/ep:Extension 
/ep:EP/ep:CorpCommonName/ep:Extension 
/ep:EP/epCorpLegalldentity/ep:Extension 
/ep:EP/ep:CorpLegalldentity/ep: VAT/ep:Extension 
/ep:EP/ep:CorpLegalldentity/ep:AltID/ep:Extension 


Open Profile /op:OP/op:Extension 
/op:OP/op:CustomizableStringsop:Extension 


package (required): The Java package name where all classes for this root are implemented. This 
includes resource description classes and data model instance classes. For example, 
com.novell.nids.profile.model.extensions. 


resourceClass (required): The Java class name of the resource description class that is used to 
load all resources associated with this root. Because resource description class files are assumed to 
reside in the root's package, only the filename is needed. Resource description classes are Java 
classes that must be created by the person extending the model. You must also extend the 
com.novell.nidp.resource.NIDPResDesc class. 


Group Element 


resourcelD: The resource ID of the display name of the group. This resource ID is assumed to be a 
key in the resource bundle supplied by the resource description class file associated with the 
containing root. 


descriptionResourcelD: The resource ID of the description of the group. This resource ID is 
assumed to be a key in the resource bundle supplied by the resource description class file associated 
with the containing root. 


Extension Element 


name (required): The name of the data model extension. This name must be the name of the XML 
element that will be used in the data model. 


1462 Data Model Extension XML 


class (optional): The Java class name of the data model instance class. Because data model 
instance class files are assumed to reside in the root’s package, only the filename is needed. If this 
attribute is omitted, then the value of the name attribute must be the instance class filename. 


syntax: The syntax of this data model extension. Possible values are: 


¢ String 

¢ LocalizedString 

e Container 
format: Required if the syntax is String or LocalizedString. The syntax of this data model extension. 
Possible values are: 

+ Caselgnore 

+ CaseExtract 

+ URI 

¢ URL 

+ Date 

+ DateNoYear 

¢ CountryCode 

e LanguageCode 

+ Keylnfo 

+ Number 
upper: The upper bound of a numeric value. Use this attribute only if the format attribute value is 


Number. The value is a signed integer. If this attribute is omitted, the default value is 
java.lang.Integer.MAX_VALUE. 


lower (optional): The lower bound of a numeric value. This attribute is only used if the format 
attribute value is Number. The value is a signed integer. If this attribute is omitted, the default value is 
java.lang.Integer.MIN_VALUE. 


min (required): The cardinality of the XML element represented by this data model extension. It is 
the minimum number of elements allowed. The value is an unsigned integer. If this attribute is 
omitted, the default value is 0. 


max (required): The cardinality of the XML element represented by this data model extension. It is 
the maximum number of elements allowed. The value is an unsigned integer. If this attribute is 
omitted, the default value is 1. The value UNBOUNDED may be used to indicate that there are no 
bounds. 


namingClass: (required if syntax equals Container and max is UNBOUNDED). The class that is 
used as the naming attribute for the container. The class must represent one of the immediate 
children of the container. This class is used to name each instance of the container. 


ValueSet Element 


A ValueSet element contains a set of fixed values that a data model entry can contain. If a data model 
extension has a ValueSet, the user interface to edit the value of that extension limits the user to these 
values. The ValueSet element has no attributes. 


Data Model Extension XML 1463 


Value Element 


A Value element represents a value in a ValueSet. It contains the actual value to be stored in the data 
model entry and the display name resource ID associated with the value. 


resourcelD (required): The resource ID of the display name of the value. This resource ID is 
assumed to be a key in the resource bundle supplied by the resource description class file associated 
with the containing root. 


value (required): The value stored in the data model entry. 


name (required): The name of the data model extension. This name must be the name of the XML 
element that is used in the data model. 


Writing Data Model Extension XML 


Data model extension XML must be defined in the namespace novell:liberty:wsf:config:1:0:0 and that 
namespace must be defined on the SchemaExtensions element. Normally, the namespace prefix 
wsfc is used. An example of data model extension XML is: 


<wsfc:SchemaExtensions xmlns:wsfc="novell:liberty:wsf:config:1:0:0"> 
<wsfc:Root parent="/pp:PP/pp:Facade/pp:Extension" 
package="com.novell.nidp.liberty.wsf.idsis.ppservice.extensions" 
resourceClass="PPExtensionsResDesc"> 
<wsfc:Group resourceId="PP.EXT.FC.GROUP" 
descriptionResourceId="PP.EXT.FC.GROUP.DESC"> 
<wsfc:Extension name="AliasName" 
class="FacadeAliasName" 
syntax="String" 
format="CaseIgnore" 
resourceId="PP.EXT.FC.AliasName" 
min="0" max="1"/> 
<wsfc:Extension name="FavoriteURLs" 
class="FacadeFavoriteURLs" 
syntax="String" 
format="CaseExact" 
resourcelId="PP.EXT.FC.FavoriteURLS" min="0" max="UNBOUNDED"/> 
</wsfc:Group> </wsfc:Root> 
<wsfc:Root parent="/pp:PP/pp:Demographics/pp:Extension" 
package="com.novell.nidp.liberty.wsf.idsis.ppservice.extensions" 
resourceClass="PPExtensionsResDesc"> 
<wsfc:Group resourceId="PP.EXT.DM.GROUP" 
descriptionResourceId="PP.EXT.DM.GROUP.DESC"> 
<wsfc:Extension name="EyeColor" 
class="DemographicsEyeColor" 
syntax="String" format="URI" 
resourceld="PP.EXT.DM.EyeColor" 
min="0" 
max="UNBOUNDED"> 
<wsfc:ValueSet> 
<wsfc:Value resourceId="PP.EXT.DM.HC.Blue" value="urn:pp:dm:blue"/> 
<wsfc:Value resourceId="PP.EXT.DM.HC.Brown" value="urn:pp:dm:brown"/> 
<wsfc:Value resourceId="PP.EXT.DM.HC.Green" value="urn:pp:dm:green"/> 
<wsfc:Value resourceId="PP.EXT.DM.HC.Gray" value="urn:pp:dm:gray"/> 
<wsfc:Value resourceId="PP.EXT.DM.HC.Hazel" value="urn:pp:dm:hazel"/> 
</wsfc:ValueSet> 
</wsfc:Extension> 
</wsfc :Group> 
</wsfc:Root> 
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<wsfc:Root parent="/pp:PP/pp:Extension" 
package="com.novell.nidp.liberty.wsf.idsis.ppservice.extensions" 
resourceClass="PPExtensionsResDesc"> 
<wsfc:Group resourceId="PP.EXT.AU.GROUP" 
descriptionResourceId="PP.EXT.AU.GROUP.DESC"> 
<wsfc:Extension name="Automobile" 
class="Automobile" 
syntax="Container" 
resourceld="PP.EXT.Automobile" 
min="0" 
max="UNBOUNDED" 
namingClass="AutomobileLicensePlate"> 
<wsfc:Group resourceId="PP.EXT.AU.DETAILS.GROUP" 
descriptionResourceId="PP.EXT.AU.DETAILS.GROUP.DESC"> 
<wsfc:Extension name="AutomobileModel" 
class="AutomobileModel" 
syntax="String" 
resourceld="PP.EXT.AU.Model" 
min="0" 
max="1"/> 
<wsfc:Extension name="AutomobileMake" 
class="AutomobileMake" 
syntax="String" 
format="CaseIgnore" 
resourceld="PP.EXT.AU.Make" 
min="0" 
max="1"/> 
<wsfc:Extension name="AutomobileLicensePlate" 
class="AutomobileLicensePlate" 
syntax="String" 
format="CaseIgnore" 
resourcelId="PP.EXT.AU.LicensePlate" 
min="0" max="1"/> 
</wsfc:Group> 
</wsfc:Extension> 
</wsfc:Group> 
</wsfc:Root> 
</wsfc:SchemaExtensions> 
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SOAP versus REST API 


The following table compares SOAP with REST: 


SOAP 


Stands for Simple Object Access Protocol 

An XML based message protocol 

Follows stateful implementation 

No error handling 

Strongly typed, strict specification for implementation 


Uses interfaces and named operations to expose 
business logic 


Both SMTP and HTTP are valid application layer 
protocols used as Transport for SOAP 


More verbose 


Uses WSDL for communication between consumer 
and provider 


Invokes services by calling RPC method 


REST 

Stands for Representational State Transfer 
Does not enforce message format 

Follows stateless model 

Built-in error handling 

Less restrictive about the implementation 


Uses URI and methods to expose resources 


Tied to the HTTP transport model 


Less verbose 


Uses XML or JSON to send and receive data 


Invokes services through URL path 
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OAuth versus Other Protocols 


The following table lists the differences among OAuth, OpenID Connect, WS-Trust, WS Fed, and 


SAML: 


Table C-1 Differences among OAuth, OpenID Connect, and WS*-Family 


OAuth 


An open protocol to allow 
secure authorization in a 
simple and standard 

method from web, mobile 
and desktop applications. 


Provides API 
authorization between 
applications. 


OpenID Connect 


Provides single sign-on 
(SSO) layer on top of the 
OAuth protocol for 
consumers. 


SAML 


An XML-based open 
standard data format for 
exchanging authentication 
and authorization data 
between an identity 
provider and a service 
provider. 


Encompasses profiles, 
bindings and constructs to 
achieve SSO, federation, 
and identity management. 


WS-* Family 


Allows secure identity 
propagation and token 
exchange between Web 
services. 


Enables applications to 
construct trusted SOAP 
message exchanges. 


OAuth tokens can be 
binary, JSON, or SAML 


Uses JSON tokens 


Deals with XML as the 
data construct or token 
format. 


Uses Request Security 
Token (RST) and Request 
Security Token Response 
(RSTR) 


Uses HTTP exclusively 


Uses HTTP exclusively 


No restriction on the 
transport format. You can 
use SOAP, JMS, or any 
transport you want to use 
to send SAML tokens or 
messages. 


No restriction on the 
transport format. You can 
use SOAP, JMS, or any 
transport you want to use 
to send SAML tokens or 
messages. 


Designed for use with 
applications on the 
Internet. 


Designed for use with 
applications on the 
Internet. 


Used in enterprise SSO 
scenarios. 


OAuth versus Other Protocols 


Used in enterprise SSO 
scenarios. 


1469 


1470 OAuth versus Other Protocols 


D Access Manager Reports Samples 


This section provides samples of reports that you can generate by using the Access Manager 
Reporting Solution Pack. 

+ “Application Access Summary Report” on page 1472 

¢ “User Application Access Summary Report” on page 1473 

+ “Application Specific User Access Report” on page 1474 

¢ “Federation Summary Report” on page 1475 

¢ “User Login Contract Summary Report” on page 1476 

¢ “User Login Failure Report” on page 1477 

+ “Application Specific Risk based Authentication Report” on page 1478 
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Application Access Summary Report 


NetIQ Access Manger 


Application Access Summary Report 


Summary of applications accessed in a given time. 


Application Access Summary 


Top Number of Application Accessed 


80 
70 E Office365 
60 E Groupwise 

E SAP 
50 _ Lotus_Notes 
40 E innerweb 

= Version One 
30 successfactors 
20 E downloads 

E SalesPoint 
10 E MS_Exchange 

0 


Duration from 2014-12-01 00:00:00 to 2014-12-17 11:41:47 


Application Name Access Count 


Total Number of Applications : 13 Total Count :192 


Groupwise 
Lotus_Notes 
OWA 

Clarity 
HR_Berry 
SalesPoint 
innerweb 
successfactors 


“A ANOS YO NHND DN 


downloads 


e : CONFIDENTIAL Jasper Reports 
JA Netia hr 


Sentinel 7.2 


NOTE: In this sample report, Office365 and SuccessFactors are names of the protected resources 
configured in Access Gateway reverse proxies. These are not federated Office 365 and Success 


Factor requests. 
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User Application Access Summary Report 


NetIQ Access Manger 


User Application Access Summary Report 


User who accessed a particular application in a given time. 


Application Access Summary for user bob 


Top Number of Application Accessed Total Number of Applications > 3 
45 
40 
35 
30 
25 E SAP 
20 E Version_One 
E MS_Exchange 
15 
10 
5 
0 
Duration from 2014-12-01 00:00:00 to 2014-12-17 12:37:48 
Application Name Access Count 
SAP 22 
Version_One 24 
MS_Exchange 44 
a Netio’ CONFIDENTIAL Jasper Reports 


Sentinel 7.2.1.0 
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Application Specific User Access Report 


NetIQ Access Manger 


Application Specific User Access Report 


Number of applications accessed by a specific user in a given time. 
Users Access Statistics for Application office365 


Top 10 Users Accessed Application :office365 


0 
Duration from 2014-12-01 00:00:00 to 2014-12-17 12:29:49 


User Access Count 


renee 2 
dawn 30 
neal 36 
amy 40 

Application Name 
Office365 
renee 10.0.2.19 
12/15/14 3:01:16 PM 
Office365 
neal 10.0.2.19 
12/15/14 3:09:23 PM 
Office365 
amy 10.0.2.19 
12/15/14 3:09:32 PM 
Office365 
amy 10.0.2.19 
12/15/14 3:09:40 PM 
Office365 
amy 10.0.2.19 
12/15/14 3:09:49 PM 
Office365 
amy 10.0.2.19 
12/15/14 3:09:57 PM 
A Netlo’ CONFIDENTIAL Jasper Reports 


Sentinel 7.2.1.0 


1474 Access Manager Reports Samples 


Federation Summary Report 


NetIQ Access Manger 


Federation Summary 


Users who accessed a federated service in a given time. 


TOTAL FEDERATED USERS FROM IDENTITY PROVIDERS AND SERVICE PROVIDERS > 10 


0 L 
14-Dec 15-Dec 16-Dec 17-Dec 18-Dex 


=] 


Duration from 2014-12-01 00:00:00 to 2014-12-17 12:42:52 


List of Identity Providers and Service Providers Count 


ID Provider 220 3 

Service Provider 99 7 
“a Net 10° CONFIDENTIAL Jasper Reports 
` Sentinel 7.2.1.0 
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User Login Contract Summary Report 


NetIQ Access Manger 
User Login Contract Summary Report 


Number of users login based on authentication contracts in a given time. 


TOTAL NUMBER OF USERS > 305 


175 

150 

125 

100 

75 

50 

25 

0 

14-Dec 15-Dec 16-Dec 17-Dec 18-Dec 
ID Provider 220 4 
WSFED 20 
Name/Password - Form 281 
A NetIQ’ CONFIDENTIAL Jasper Reports 


Sentinel 7.2.1.0 
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User Login Failure Report 


NetIQ Access Manger 
User Login Failure Report 
Number of failed login attempts and their reasons. 


TOTAL LOGIN FAILURE COUNT »=3 


3.0 
2.5 
2.0 
1.5 
1.0 


0.5 


0.0 
23-Mar, 00:00 23-Mar, 12:00 24-Mar, 00:00 24-Mar, 12:00 25-Mar, 0( 


+Æ- Login Failure 


Duration from 2015-03-22 00:00:00 to 2015-03-24 14:46:51 


Login Failure Reason Count 


Unable to locate user name 1 
Account is restricted for user 1 
Incorrect password was entered for user 1 


(7 


Incorrect password was entered for user verde 40.0.1.20 
15 2:45:48 PM 


Unable to locate user name 


dawn 10.0.1.20 
3/24/15 2:45:48 PM 
Account is restricted for user bob 10.0.1.20 
3/24/15 2:45:48 PM 
~~ Netlo’ CONFIDENTIAL Jasper Reports 


Sentinel 7.2.1.0 
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Application Specific Risk based Authentication 
Report 


NetIQ Access Manager 
Application Specific Risk based Authentication Report 


Summary of Risk Based Authentication for particular application in a given time. 


Total Risk Based Authentications For Applicaton + RBA-PS 33 
30 


25 


20 


15 


10 


“ 


0 
18-Nov 19-Nov 20-Nov 21-No\ 


Æ Risk Based Authentication 


Duration from 2015-1 1-19 00:00:00 to 2015-11-20 16.96.39 


Risk Level Access Count 


High & 
Medien "1 
Low 14 
iota Tak a Acton 
on=micky,o=\novell 20 
11/20/15 10 J6 AM Medius STEP_UP/Additional authentication 
cnejulia,o=ywvell 0 
20/15 10:49:13 AM Low Deny On Rule Pass Executed DENY 
cn=alca.o=\novell 20 
11/20/15 10:45:42 AM Low ALLOW 
Gn=bod, o= novell 20 
20/15 10 45:13 AM Low ALLOW 
=alica_o=\novell 20 
11/19/15 9:53:00 PM Low ALLOW 
cn=alice.o=\novell 0 
1119/15 9:52:21 PM L Dany On Rute Pass Executed DENY 
onsahce os\novell 0 
1/19/15 9:50:35 PM Low Deny On Rule Pass Executed. DENY 
cn=alice.o=novell 20 
1/19/15 9:50:12 PM Madivam STEP_UP/Adaitional authentication 
onsaice o=\novell 20 
1/19/15 9:4902 PM Medium STEP_UP/Additional authentication 
Sa Netia’ CONFIDENTIAL entire 7.31 
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